Interop::GetCallbackPtr

The Interop::GetCallbackPtr function returns a pointer to a native function for callback use. This is useful when calling a function in an external library (like the Windows API) that requires a function address as parameter to send its result.

Syntax

[number] GetCallbackPtr(
    [string] FunctionName
);

Parameters

FunctionName

[string] Name of a function present in your script, used for the callback. Its number of parameters must match exactly the number of parameters needed by the callback or the call may crash Messenger. The callback function can not have more than 6 parameters. See remarks.

Return Value

The address of a function to use as parameter in Call. This value must be used immediately and not stored for later or repeated use.

This function typically fails for the following reasons:

• The specified function does not exist in the script.
• The specified function has more than 6 parameters.
• The function was called from the global scope (GetCallbackPtr must be called from within a function in your script).

Remarks

Developers who use callback functions must be very careful about the functions they call and the parameters they accept. Here is a list of requirements for this function to succeed:

• The callback function called by the callee must use the __stdcall calling convention, also referred as WINAPI or CALLBACK in some places.
• The callback function must return something (it can't be "void") even if the value has no particular meaning.
• The callback function, as declared in the script, must have exactly the same number of parameters as specified in the documentation of the callee.
• All the parameters sent in the callback function are sent as numbers. This means that parameters like strings will be sent as addresses. Messenger Plus! does not try to interpret any parameter, it is your responsibility to do so.

The address returned by this function must be used immediately. This means that the only place allowed for the call is Interop.Call and Interop.Call2.

Remember that the use of callback functions is restricted to synchronous calls. This means that all the calls made to the callback function must be done before the callee returns. Asynchronous calls are not permitted and must not be attempted in any circumstances.

Example

This code traces the list of handles (numbers) of all the top-level windows currently displayed in the user's session.

function OnEvent_Initialize(MessengerStart)
{
      Debug.Trace("EnumWindows result:");
      Interop.Call("User32.dll", "EnumWindows", Interop.GetCallbackPtr("EnumCallback"), 0);
}

function EnumCallback(hWnd, lParam)
{
      Debug.Trace("   - window handle: " + hWnd);
      return true;
}

Function Information

See Also

Interop Object, Call.