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
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.