info.mailtraq.com > Management > Script Functions A-Z > CallDllFunction() CallDllFunction()Using this function, Mailtraq can be integrated with other software or complex functionality can be added to Mailtraq which would not be possible with the scripting functions alone. This function is also a key part of the Mailtraq Plug-ins mechanism. CallDLLFunction()calls another user-defined function stored in a Dynamic Link Library (DLL). The user-defined function must be exported from the library in the same way as any .DLL function (i.e. standard 'C' type parameters). Communication between Mailtraq and the DLL function take place through a shared block of memory (allocated and released by Mailtraq). The DLL function must return a single 32-bit integer (which must contain zero), and take two parameters: a 32-bit integer defining the size of the memory block, followed by a 32-bit pointer to the start of that block.
'C' Prototype
int FunctionName(int size, char *ptr);
Pascal Prototype
function FunctionName(size: Integer; ptr: PChar): Integer; stdcall;
Note the use of the keyword stdcall in the Pascal prototype. If this is not used, the parameters will be read from the register instead of the stack, causing unpredictable problems.
Mailtraq passes the parameters given in the CallDLLFunction() in the form of a null-terminated string, entered into the shared memory block. When the function is completed, the contents of the memory block is assumed to be a null-terminated string, and is returned as the result of the CallDLLFunction().
It is a good idea to bind regularly used function to scripting functions using Define() . These function definitions can be stored in a single file that can be called by any script wishing to use the library functions.
result := CallDLLFunction( library , function , [ parameters ], [ datasize ])
- library
- The full path name of the DLL which will contain the requested name of the function to execute in the DLL
- function
- The name of the function to execute in the DLL. This should be the exported name of the function
- parameters
- This optional parameter is a text string that is placed in the shared data-block prior to the DLL function being executed
- datasize
- This optional parameter determines how large the memory block will be. This is also the maximum size of the data that can be passed between Mailtraq and the DLL function. If this value is not given, the default of 256 will be used
- result
- This is the text string contained in the memory block after the function has been executed. If the function does not modify the memory block then this will be the same as the parameters value
Shows how two external DLL functions (for accessing registry data) are bound to more user-friendly Mailtraq functions. The definitions could have been stored in a separate file, called with the CallScript() function at the start of any script that might need them. Func_Lib := "c:\lib\myfuncs.dll";
Define("RegReadVal",
CallDLLFunction(Func_Lib, "RegReadVal", $1, 4096)
);
Define("RegWriteVal",
CallDLLFunction(Func_Lib, "RegWriteVal", $1 ++ "=" ++ $2, 4096)
);
val := RegReadVal("\Software\MyProgram\Value1");
RegWriteVal("\Software\MyProgram\Value2", val) |