CALLBACKS EXPLAINED

by Alyce Watson

Home

Contest Update

Liberty BASIC 3!

Open Source Editor

Tip Corner

Callbacks Explained

Drag 'n' Drop

Drag 'n' Drop in LB3

Gnu Liberty BASIC Compiler

LB2BCX

Newsletter Help

Index

Callbacks require Liberty BASIC 3.

Callbacks are one of the more complex aspects or Liberty BASIC programming. If you are new to programming, or if you do not have a thorough knowledge of making API calls, then you might want to put this article away for future consideration.

A 'callback' is the address of a program function that is used as a parameter in API call. The API function contacts your program's function and sends it information, in the form of a parameter list. Your program's function then performs the desired action. Your program's function may make use of the parameters in the list. When your program's function is finished, it should return a value to the calling function. If it returns 0, the calling function will stop itself from running and return control to your program. Your program's function should return nonzero if it wants to let the API function to continue to execute.

API calls with "Enum" in their names generally require callbacks. These functions will enumerate some system entities, sending the list to your function one at a time. Your function processes each of these items as they are sent to it by the API function. When the input parameters from the API function give no further information to your program's function, or when your program has processed some set maximum number of items, then it returns 0 to the calling API function to cause the API function to quit execution and return control to your program.

The syntax is:

callback addressPTR, functionName(type1, type2...), returnValue

Usage:

addressPTR

assigns a name to the memory address of the function. This memory address will be passed into the API function that requires a callback.

functionName

is the name of the function in the Liberty BASIC program that will be called by the API function.

(type1, type2...)

a comma-separated list of parameters, which will be specific to the function used. The parameters must be valid data TYPES such as "ulong" and "long". API functions require different numbers of parameters, depending upon the individual function.

returnValue

the type of return value is listed after the closing parenthesis. The Liberty BASIC function may return a value to the calling function. Some calling functions evaluate this return, and when YOUR function returns 0 to the calling function, it stops itself from running and returns control to your program.

Some API functions that require callbacks:

Look in the documentation provided by Microsoft in its Software Developers Kits or on the MSDN to discover the correct format for the function your program must provide for the API function. The functions you must provide for the above sample list are:

For a working example of using an Enum Function with a callback, see the LB3 helpfile "EnumWindows" example in the CALLBACK section.

Here is a generic program to demonstrate callbacks. This is NOT a REAL program!

'generic, non-working code example:
texteditor #win.te, 10, 10, 250, 250
open "Enum Something Example" for window as #win
print #win, "trapclose [quit]"

'set the variable named address to be the memory address for
'EnumSomethingProc() using types long and ulong, and set
'the return type of EnumSomethingProc() to be a boolean

callback myAddress, EnumSomethingProc(long, ulong), boolean

open "mydll" for dll as #dummy

'call EnumWindows, which in turn calls back into the
'BASIC function at address.

calldll #dummy, "EnumSomething", _
    myAddress as ulong, _
    0 as long, _
    result as boolean

close #dummy

wait

[quit]
close #win
end

function EnumSomethingProc(wParam, lParam)
    print #win.te, "wParam is ";wParam
    print #win.te, "lParam is ";lParam

    'check conditions to choose a return
    'value based upon the param list values
    'returning 0 causes EnumSomething to 
    'return control to the program

    if lParam=0 or wParam=0 then
        EnumSomethingProc = 0   
      else
        EnumSomethingProc = 1
    end if

    'if your program returns nonzero to
    'EnumSomething, then it will continue
    'running and send your function
    'another callback and list of params.

end function

Callbacks are required for the wmliberty.dll which is used in the Drag 'n' Drop example later in the newsletter, written by Mitchell Kotler.


Home

Contest Update

Liberty BASIC 3!

Open Source Editor

Tip Corner

Callbacks Explained

Drag 'n' Drop

Drag 'n' Drop in LB3

Gnu Liberty BASIC Compiler

LB2BCX

Newsletter Help

Index