Calls an external DLL using the Cdecl calling convention.
DllCallCdecl(dllname, returntype:epname [,paramtype:parameter ...] )
(s) dllname The name of the Dll to be called, or a handle returned by the DllLoad function.
(t) returntype: Type of value the Dll entry point will return (see below).
(s) epname Entry point name/ordinal number into the Dll.
(t) paramtype Type of parameter (see below).
(?) parameters Parameters as required by the entry point.
Value returned by the DllCallCdecl depends on the external Dll. It may be either a integer or a string. See discussion below.
This function is the same as DllCall, except it calls DLL functions using the Cdecl calling convention, rather than the StdCall calling convention which most Win32 DLL's use.
DllCallCdecl is designed to allow sophisticated users to either write their own extensions to the WIL language (using the Windows SDK), to call third party Dll’s, or to access Windows API’s directly.
In order to use this function properly, a little background is necessary. There exists a number of very specific reasons one would want to call an external DLL to process some code. Examples may include calling Dll’s to interface with certain hardware devices, to perform special compute-intensive algorithms, or to perform a series of functions not possible using the WIL language. In many cases, the user has no control over the DLL’s to be called, so that the WIL DllCallCdecl statement must be able to call a wide variety of Dll’s, to be able to pass an assortment of different parameter types, and to be able to process a number of different return values.
For this reason, the DllCallCdecl syntax is complicated and initially confusing. Use of the DllCallCdecl requires detailed understanding of Windows programming and complete documentation for the Dll and the Dll entry point being called. If you need tech support help with the DllCallCdecl statement, you must provide (email, fax, etc.) pertinent documentation before calling for help
To call an external Dll, the user must first determine the following information:
1) Name of the DLL.
2) Entry point name of the desired function within the Dll.
3) Type of the return value from the Dll.
4) Number of passed parameters the Entry point requires.
5) Type of each of the passed parameters.
WIL supports the following types of return types from a Dll:
1) word 16-bit integer
2) long 32-bit integer
3) lpstr 32-bit pointer to an ANSI string
4) lpwstr 32-bit pointer to a Unicode string
5) void no return value
6) double 64-bit floating point value
7) long_ptr 32-bit integer value when used with 32-bit WinBatch and a 64-bit value when used with 64-bit WinBatch
WIL supports the following parameter types to pass data to a Dll:
1) word 16-bit integer
2) long 32-bit integer
3) lpstr 32-bit pointer to an ANSI string
4) lpwstr 32-bit pointer to a Unicode string
5) lpstruct Dll structure handle returned by the DllStructAlloc.
6) lpnull 32-bit NULL pointer
7) lpbinary 32-bit pointer to a memory block allocated with the BinaryAlloc function. See section on Binary Operations.
8) double 64-bit floating point value
9) callback 32-bit integer created using DllCallbackCreate
10) long_ptr Integer value guaranteed to be the bit size of a memory address. That is, a 32-bit integer value when used with 32-bit WinBatch and a 64-bit value when used with 64-bit WinBatch
Note: If lpbinary is used to pass information from a Dll back to a WIL script via a DllCallCdecl, then be sure to use BinaryEodSet to manually set the end of data point so that the other binary functions can reference the returned data.
The DllCallCdecl parameters are as follows:
First: The first parameter defined the Dll to be used. It can either be a dllname or a dllhandle. A dllname may be used for "oneshot" types of calls where a single call to the Dll is all that is required, or when each call to the Dll is independent of all other calls. A dllhandle is used for multiple calls to a Dll, where the calls are interrelated -- perhaps the first call to initialize the Dll, other calls use it, and a final call to terminate processing. In such cases the Dll must first be loaded with the DllLoad function, and freed with the DllFree function. The first parameter must be one of the following:
dllname: Simply the filename of the Dll that contains the desired entry point name. A single Dll may contain one to many separate entry points. Each entry point may have its own unique return type and parameter list.
dllhandle: A handle to a Dll obtained from the DllLoad function.
Second: The second parameter consists of two parts, the first part is the return type of the entry point desired, followed by a colon (:), and the second part is the entry point name itself.
Note: Only use the lpstr or lpwstr return type for entry points that returns actual text strings. In some cases other documentation might suggest using a lpstr or lpwstr as a return type for its structures, don’t. Use long instead.
For each parameter the entry point requires, an additional parameter is added to the DllCallCdecl parameter list. DllCallCdecl is limited to passing up to 20 parameters total. If the entry point has no parameters, then the DllCallCdecl function uses only the first and second parameters as described above.
Additional: For each parameter that the entry point in the Dll requires, additional DllCallCdecl parameters are added. Each additional parameter consists of two parts, the first part is the parameter type of the required parameter, followed by a colon (:), and the second part is the parameter itself.
format = "Hello %%s"
username = "Dolly"
buffer = BinaryAlloc(512)
dllname = StrCat(DirWindows(1), "USER32.DLL")
len = DllCallCDecl(dllname, long:"wsprintfA", lpbinary:buffer, lpstr:format, lpstr:username)
BinaryEodSet(buffer, len)
STRING = BinaryPeekStr(buffer, 0, len)
BinaryFree(buffer)
Message("", STRING)
For an example ON how To use binary buffers To Receive data returned through a passed pointer, see the DllHwnd example.
DataCast, DllCall, DllCall Additional information, Binary Operations, DllCallbackCreate, DllCallbackDestroy, DllLoad, DllFree, DllHwnd, DllHinst, DllStructAlloc, DllStructPeek, DllStructPoke, DllStructFree