Interop::Call

The Interop::Call function allows scripts to call functions located in external libraries. For example, it can be used to call functions from the Windows API.

Syntax

[number] Call(
    [string] DllName,
    [string] FunctionName,
    [var, optional] Param1,
    [var, optional] Param2,
    [var, optional] Param3,
    [var, optional] Param4,
    [var, optional] Param5,
    [var, optional] Param6,
    [var, optional] Param7,
    [var, optional] Param8,
    [var, optional] Param9,
    [var, optional] Param10,
    [var, optional] Param11,
    [var, optional] Param12
);

Parameters

DllName

[string] Path to the DLL file where the function to call is located. If multiple calls are made to the same DLL, the DLL is loaded only once and stays in memory until FreeDll is called or the script is terminated. The DLL file will be located by using the standard "LoadLibrary" mechanism described here. As no "current directory" is guaranteed for your script, you'll need to use MsgPlus.ScriptFilesPath to load a library from your script's directory.

FunctionName

[string] Name of the function as specified in the export table of the library. The function must use the __stdcall calling convention. See Remarks.

Param1

[var, optional] First parameter to send to the function, if any.

Here is how the data will be sent to the function depending on its type:

• If the parameter is a plain number (positive or negative), it is sent as is.

• If the parameter is a floating point number, it is rounded up and sent as a plain number.

• If the parameter is a boolean, a number is sent: 1 for true, 0 for false.

• If the parameter is null, 0 is sent.

• If the parameter is a string, a pointer to a Unicode string is sent.

• If the parameter is a DataBloc object, a pointer to its underlying data is sent.

• If the parameter is any other object, a pointer to its IDispatch interface is sent. The reference count of the object is not increased.

Param2

[var, optional] Second parameter to send to the function, if any. See Param1.

Param3

[var, optional] Third parameter to send to the function, if any. See Param1.

Param4

[var, optional] Fourth parameter to send to the function, if any. See Param1.

Param5

[var, optional] Fifth parameter to send to the function, if any. See Param1.

Param6

[var, optional] Sixth parameter to send to the function, if any. See Param1.

Param7

[var, optional] Seventh parameter to send to the function, if any. See Param1.

Param8

[var, optional] Eighth parameter to send to the function, if any. See Param1.

Param9

[var, optional] Ninth parameter to send to the function, if any. See Param1.

Param10

[var, optional] Tenth parameter to send to the function, if any. Accepted only in Messenger Plus! Live 4.21 and above. See Param1.

Param11

[var, optional] Eleventh parameter to send to the function, if any. Accepted only in Messenger Plus! Live 4.21 and above. See Param1.

Param12

[var, optional] Twelfth parameter to send to the function, if any. Accepted only in Messenger Plus! Live 4.21 and above. See Param1.

Return Value

A number, returned by the function. The meaning of this number depends on the function called.

This function typically fails for the following reasons:

• The DLL couldn't be located on the system.
• The function couldn't be located in the specified DLL.
• An exception was thrown during the function call.

Messenger Plus! Live 4.10 and above: an error is logged in the Script Debugging window when an exception is thrown during the call (often caused by incorrect parameters).

Remarks

Developers who use this function 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 function called must use the __stdcall calling convention, also referred as WINAPI in some places.
• The function must return something (it can't be "void") even if the value has no particular meaning.
• The function must not take more than 12 parameters in Messenger Plus! Live 4.21+ and 9 parameters in older versions.
• The function must accept Unicode string (although ANSI string may be sent with a DataBloc).

Most functions from the Windows API use the __stdcall convention, although you have to be careful to always use the "wide" version of each function. This means for example that to display a message box, you need to call "MessageBoxW". Calling a function with incorrect parameters will corrupt the Messenger memory space and eventually crash the program.

Messenger Plus! Live 4.10 and above: Messenger Plus! tries to detect bad calling conventions (when __stdcall was not used to declare the function that's being called) and logs the corresponding error in the Script Debugging window. Do NOT ignore these errors, they will cause instabilities and eventually crash Messenger in random places.

Example

This code displays a "Hello!" message box.

Interop.Call("User32.dll", "MessageBoxW", 0, "Hello!", "Example Message", 0);

Function Information

See Also

Interop Object, DataBloc Object, Call2.