CALLBACK

Description:

A Callback is the address of a program function that is used as a parameter in API call. The syntax is:

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

(Note: Callbacks are an advanced programming technique. They should only be used by programmers with a good, working knowledge of calling API functions with CALLDLL.)

A CALLBACK command sets up a memory address for the function specified in the command. An API function can then use this address to call the specified function many times, hence the term CALLBACK. Most API functions are called once, and return a single value. A CALLBACK function interacts with the program many times. The parameters are explained in more detail below.

Usage:

addressPTR

This parameter assigns a name to the memory address of the function. This name is used in the API call that requires the memory address.

functionName

This parameter is the name of the function in the Liberty BASIC program that is called by the API function.

(type1, type2...)

The CALLBACK statement requires a comma-separated list of parameters, is specific to the function used. Most Windows API references contain documentation for the particular functions available. The parameters must be valid data TYPES such as "ulong" and "long".

returnValue

The TYPE of the return value is listed after the closing parenthesis. The Liberty BASIC function can return a value to the calling function.

In the following demo, the Liberty BASIC function keeps an internal count, and returns 1 if it is continuing to process information and 0 when it returns control to the calling function. It prints the names of the first 5 windows that are sent to it by the EnumWindows API, then returns control to the calling function.

  texteditor #win.te, 10, 10, 250, 250
  open "Enum Windows Example" for window as #win
  print #win, "trapclose [quit]"
  'set the variable named address to be the memory address for
  'enumWndProc() using TYPES handle and ulong, and set
  'the return TYPE of enumWndProc() to be a boolean
  callback address, enumWndProc(handle, ulong), boolean
  'call EnumWindows, which in turn calls back into the
  'BASIC function at address.
  calldll #user32, "EnumWindows", _
    address as ulong, _
    0 as long, _
    result as boolean
  wait
[quit]
  close #win
  end

function enumWndProc(hwnd, lparam)
  labelBuffer$ = space$(71)
  calldll #user32, "GetWindowTextA", _
    hwnd as ulong, _
    labelBuffer$ as ptr, _
    70 as long, _
    result as long
  if left$(labelBuffer$, 1) <> chr$(0) then
    print #win.te, labelBuffer$
    call setCount getCount()+1
  end if
  if getCount() = 5 then
    enumWndProc = 0 'returning 0 causes EnumWindows to return
  else
    enumWndProc = 1
  end if
end function

sub setCount value
  count(0) = value
end sub

function getCount()
  getCount = count(0)
end function