ExamplesCallFn( Function, HasDisplay, Return, params <Type, Value, Type, Value > )
Note that function names and representations of types (ulong, float etc) are surrounded by quotation marks while the actual values (numbers, true, false) are not. The chevrons bracketing the series of params are for clarity and need not be included.
A value of the type specified by the calling parameters. In the event of any error, the return value is -1.
Function The name of the function to call. This must match the exported function name in the DLL. This parameter is required.
HasDisplay This allows you to specify whether the DLL call will display a user-interface and thereby allows the interface to be active. This is a boolean which means the two options are true or false. This parameter is required.
Return The type of the return value from the function (if any). This parameter is a string and must be one of the following values:
| Value | C/C++ Data Type |
| "none" | void |
| "uchar" | unsigned char |
| "schar" | signed char |
| "ushort" | unsigned short |
| "sshort" | signed short |
| "ulong" | unsigned long |
| "slong" | signed long |
| "float" | float |
| "string" | unsigned char pointer (unsigned char*) Note: It is the responsibility of the DLL to ensure that the memory pointed to remains valid after the return of the function call. |
Note:
Even if you do not intend to use the return value, if the DLL function declares one you must specify it in order for the function to be called correctly.
Note:
ecmascript (and therefore OpusScript) does not support unsigned values, so they will be converted to a signed value. This can result in conversion errors for very large unsigned values.
Params The parameters to be passed to the function. These parameters must be specified in pairs the first is the type of the parameter and the second is the value to pass. integer numbers (unsigned long) or zero-terminated strings (char*)
A special type is included, hwnd, which provides a handle to the Window the call is happening in (if appropriate). This allows DLL authors to make their displays as children of the Opus publication window and thereby (for example) centring their display in the the publication window. The value part of this type/value pair is ignored so we recommend that it is simply set to 0.
| Type | Type declared in DLL function |
| "ulong" | unsigned long |
| "slong" | signed long |
| "float" | float |
| "string" | unsigned char* |
| "hwnd" | handle to window |
This function allows functions within external DLLs to be called from OpusScript.
Please be aware that ecmascript (and therefore OpusScript) is a loosely typed language; that is any variable can be treated as any type and will be automatically converted without warning.
If a DLL requires more complex argument types than those supported by CallFn, it may be possible to write a "wrapper" DLL that contains a simplified interface that only uses data types understood by OpusScript.