DllCall
Calls a function in an application's dynamic-link library (DLL). There are three forms of this command. The first does not return a value. The second is a function that returns an integer (LONG/DWORD) value. The third is a function that returns a string value.
In the first two forms, the DLL function must be a PASCAL function that takes a single LPCSTR (long pointer to a constant string) argument. In the third form, the DLL function must take three arguments, an LPCSTR, a pointer to a BYTE buffer, and an integer.
C or C++ DLL functions called by the first form of DllCall must have prototypes equivalent to:
extern "C" __declspec(dllexport) void __stdcall fn(LPCTSTR szParam );
C or C++ DLL functions called by the second form of DllCall must have prototypes equivalent to:
extern "C" __declspec(dllexport) dword __stdcall fn(LPCTSTR szParam );
C or C++ DLL functions called by the third form of DllCall must have prototypes equivalent to:
extern "C" __declspec(dllexport) void __stdcall fn(LPCTSTR szParam , BYTE *pBuffer, int cMax);
Syntax
DllCall "libName", "function", "argString"
integerVariable& = DllCall ("libName", "function", "argString")
stringVariable$ = DllCall$ ("libName", "function", "argString", "maxStringLength")
| Argument | Description |
|---|---|
| libName | The name of the .DLL file to be called. The DllCall command works even if the dynamic-link file does not have a .DLL extension. The value can be an expression. |
| function | The name or number of the .DLL file function to call. If a number is used, do not enclose the value in quotation marks. The value cannot be an expression. |
| argString | The string containing the data to be passed to the dynamic-link function. The value can be an expression. This argument is passed as the first (or only) argument to the DLL function. |
| maxStringLength | Maximum length of the string that the DLL can return as stringVariable. Dragon uses this argument to reserve space for the string returned by the DLL call and passes it as the third argument to the DLL function. The value can be an expression. |
| Return Value | Description |
|---|---|
| integerVariable& | The Dll function must return an integer. DllCall sets integerVariable& to this value. |
| stringVariable$ | The Dll function must return a string by reference. DllCall sets stringVariable$ to the string value. |
Notes
- Improper use of the DllCall command can cause applications to hang and under some circumstances may require you to restart the computer. In particular, you should make sure that the form of the call and the argument string match the DLL function that you are calling.
- You can use the DllCall command to add application extensions to the Dragon scripting language.
- As a general rule, do not call Windows system .DLL files. However, you can write a DLL with functions that convert the contents of the stringArg from a single string into the appropriate arguments for a Windows DLL call and then make the required Windows calls.
- This command loads and releases the DLL each time you use it. If you make frequent DLLCalls to the same DLL, you can have another process load the DLL (and not unload it) to ensure that the DLL stays in memory.