DllCall

Calls an external DLL.

Syntax:

DllCall ( dllname, returntype:epname [,paramtype:parameter ...] )

Parameters:

(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.

Returns:

(i/s) Value returned by the DllCall depends on the external Dll. It may be either a integer or a string. See discussion below.

The DllCall function is unlike all other WIL functions. It 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 DllCall 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 DllCall syntax is complicated and initially confusing. Use of the DllCall 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 DllCall statement, you must provide pertinent documentation before calling for help.

To call an external Dll, the user must first determine the following information:

Name of the DLL.
Entry point name of the desired function within the Dll.
Type of the return value from the Dll.
Number of passed parameters the Entry point requires.
Type of each of the passed parameters.

WIL supports the following types of return types from a Dll:

word 16-bit integer
long 32-bit integer
lpstr 32-bit pointer to an ANSI string
lpwstr 32-bit pointer to a Unicode string
void no return value
double 64-bit floating point value
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:

word 16-bit integer
long 32-bit integer
lpstr 32-bit/64-bit pointer to an ANSI string
lpwstr 32-bit/64-bit pointer to a Unicode string
lpstruct Dll structure handle returned by the DllStructAlloc.
lpnull 32-bit/64-bit NULL pointer
lpbinary 32-bit/64-bit pointer to a memory block allocated with the BinaryAlloc function. See section on Binary Operations.
double 64-bit floating point value
callback 32-bit integer created using DllCallbackCreate
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 DllCall, 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 DllCall 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 DllCall parameter list. If the entry point has no parameters, then the DllCall function uses only the first and second parameters as described above.

Additional: For each parameter that the entry point in the Dll requires, additional DllCall 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. DllCall is limited to passing up to 20 parameters.

Example:

; DllCall example.
; This example calls the CharUpperA API in the Windows User module.
; The CharUpperA function requires a 32-bit pointer to a string (lpstr).
; It converts the string to uppercase and passes back a 32-bit
; pointer (also lpstr) to the uppercased string.
; The CharUpperA function is found in the Windows USER32.Dll.
; Note: Dll Name, being a normal string is in quotes.
; Entry point name, also being a string, is also in quotes
; Parameter a0, being a normal variable is not in quotes.
a0="Hello Dolly"
dllname=StrCat(DirWindows(1),"USER32.DLL")
a1=DllCall(dllname, lpstr:"CharUpperA", lpstr:a0)
Message(a0,a1)

; DllCall with Callback example. 

#DefineFunction udfEnumWindowsProc(hwnd, lparam)
      ; This callback will run until:
      ;   Callback returns FALSE
      ;   There are no more top level windows to enumerate
      maxsize = 256
      lptitle = BinaryAlloc(maxsize)
      BinaryEodSet(lptitle, 0)
      length = DllCall(DirWindows(1):'user32.dll', long:'GetWindowTextA',long:hwnd,lpbinary:lptitle,long:maxsize)
      If length>1
         BinaryEodSet(lptitle, length)
         title = BinaryPeekStr(lptitle, 0, length)
         If StrIndex( title, lparam, 1, @FWDSCAN )
            ret = AskYesNo( lparam:' window exists!', 'Close this window? [':title:']' )
            If ret == @YES Then WinClose(title) ;Close Window
         EndIf
      EndIf
      BinaryFree(lptitle)
      Return @TRUE
#EndFunction

; Locates window and closes it
lookfortitle = 'Notepad'
ShellExecute('Notepad.exe', '', '', @NORMAL, '')
TimeDelay(1)
cbhandle = DllCallbackCreate('udfEnumWindowsProc', 'LONG', 'LONG LPSTR')
ret = DllCall( DirWindows(1):'user32.dll', long:'EnumWindows',callback:cbhandle,lpstr:lookfortitle)
DllCallbackDestroy(cbhandle)
Exit

DllCall

Syntax:

Parameters:

Returns:

Example:

See Also: