PC SOFT

ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Home | Sign in | English EN
  • Checks performed
  • Managing errors
  • Loading and unloading the DLL
  • Parameters that will be passed to the function of DLL
  • Passing a string to an API or retrieving a string from an API
  • Passing a structure containing a string to an API
  • Procedure called in CallBack
  • Miscellaneous
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Runs a function found in an external DLL. This function can be a function of Windows API. The functions accessible by CallDLL32 are the functions of the standard libraries of Windows (USER32, KERNEL32, GDI32, etc.).
The function can be identified by:
  • its name.
  • its number.
  • Versions 16 and later
    its address.
    New in version 16
    its address.
    its address.
Versions 16 and later
It is also possible to use a variable of type API description. For APIs that use parameters of specific types or that are called multiple times in the same application, it is recommended to use an API Description variable directly (without using the CallDLL32 function).
New in version 16
It is also possible to use a variable of type API description. For APIs that use parameters of specific types or that are called multiple times in the same application, it is recommended to use an API Description variable directly (without using the CallDLL32 function).
It is also possible to use a variable of type API description. For APIs that use parameters of specific types or that are called multiple times in the same application, it is recommended to use an API Description variable directly (without using the CallDLL32 function).
Remarks:
  • This function is equivalent to API.
  • Versions 16 and later
    If the function to run contains QWORD parameters, you must use an API description variable (Syntax 4)
    New in version 16
    If the function to run contains QWORD parameters, you must use an API description variable (Syntax 4)
    If the function to run contains QWORD parameters, you must use an API description variable (Syntax 4).
CallDLL32("USER32", "SendMessageA", hWnd, wMsg, lParam1, lParam2)
Syntax

Running a function of an external DLL or a function of the Windows API identified by its name Hide the details

<Result> = CallDLL32(<DLL name> , <Function name> [, <Parameter 1> [... [, <Parameter N>]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <Function name>. This result can be an error code. The type of this result depends on the function run. For more details, see the documentation about this function.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<DLL name>: Character string
Name of library (DLL) containing the function to run.
<Function name>: Character string
Name of function to run. This function must be found in the specified DLL.
<Parameter 1>: Type corresponding to the parameter (optional)
First parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter N>: Type corresponding to the parameter (optional)
Nth parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).

Running a function of an external DLL or a function of Windows API identified by its number Hide the details

<Result> = CallDLL32(<DLL name> , <Function number> [, <Parameter 1> [... [, <Parameter N>]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <Function name>. This result can be an error code. The type of this result depends on the function run. For more details, see the documentation about this function.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<DLL name>: Character string
Name of library (DLL) containing the function to run.
<Function number>: Character string
Number of the function to run. This function must be found in the specified DLL.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter N>: Type corresponding to the parameter
Nth parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
Versions 16 and later

Running a function of an external DLL or a function of the Windows API identified by its address Hide the details

<Result> = CallDLL32(<Function address> [, <Parameter 1> [... [, <Parameter N>]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <Function name>. This result can be an error code. The type of this result depends on the function run. For more details, see the documentation about this function.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Function address>: Integer
Address in memory of the function to run.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter N>: Type corresponding to the parameter
Nth parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
New in version 16

Running a function of an external DLL or a function of the Windows API identified by its address Hide the details

<Result> = CallDLL32(<Function address> [, <Parameter 1> [... [, <Parameter N>]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <Function name>. This result can be an error code. The type of this result depends on the function run. For more details, see the documentation about this function.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Function address>: Integer
Address in memory of the function to run.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter N>: Type corresponding to the parameter
Nth parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).

Running a function of an external DLL or a function of the Windows API identified by its address Hide the details

<Result> = CallDLL32(<Function address> [, <Parameter 1> [... [, <Parameter N>]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <Function name>. This result can be an error code. The type of this result depends on the function run. For more details, see the documentation about this function.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Function address>: Integer
Address in memory of the function to run.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter N>: Type corresponding to the parameter
Nth parameter that will be passed to the function. These parameters must have the same type as the parameters expected by the function. Can be used:
  • the "simple" types (see Notes),
  • the structures (see Notes),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
Remarks

Checks performed

  • CallDLL32 is protected against "General Protection Faults" in the function called. Nevertheless, a WLanguage error is triggered if this type of error occurs.
  • For the functions following the PASCAL call prototype (especially the functions of the Windows API), a simple check on the number of parameters passed to the function is performed. A WLanguage error occurs in case of discrepancy.

Managing errors

When running functions of the Windows API, if the result returned corresponds to an error, use ErrorInfo (associated with the errSystemCode or errSystemMessage constant) to find out the error details.

Loading and unloading the DLL

CallDLL32 automatically loads the DLL if necessary, then it unloads it (if it was loaded). This mechanism can be quite slow, except for the system DLLs (KERNEL, USER, GDI).
To optimize the execution speed, we advise you to load the DLL once with LoadDLL and to unload it with FreeDLL when it is no longer used.

Parameters that will be passed to the function of DLL

These parameters must have the same type as the parameters expected by the function.
The available types are as follows:
  • The "simple" types (integer, real and boolean). Using another WLanguage type triggers a WLanguage error.
    If the function to run expects a pointer or a Windows handle, use a system integer.
    If the function to run expects an address, use the & operator.
  • The "string" types.
  • The structure types.
  • A name of WLanguage procedure. This procedure will be called by the function of the DLL (see the paragraph below).
    The parameters depend on the function run. See the documentation about this function for more details.

Passing a string to an API or retrieving a string from an API

  1. In input parameter, use the string type. For example:
    sString is string
    CallDll32(<DLL>, <Function>, sString)
  2. In output parameter, the C language cannot easily manage the dynamic strings. Therefore, you must:
    • define a maximum size, with the "String on" type. For example:
      sString is string on 100
      CallDLL32(<DLL>, <Function>, sString)
      // in Method in C:
      // STRNCPY(PointerInC, "Test", 100)
    • retrieve the addresses of strings in C (however, in this case, the code section in C must "preserve" the strings returned), then transfer the string into a string variable with StringRetrieve. For example:
      nStringAddress is system int
      CallDLL32(<DLL>, <Function>, &nStringAddress)
      sString is string
      sString = StringRetrieve(nStringAddress, srASCIIZAddress)
      // in Method in C: *PointerInC = "Test"
  3. In return value, retrieve the addresses of strings in C (however, in this case, the code section in C must "preserve" the strings returned), then transfer the string into a string variable with StringRetrieve. For example:
    nStringAddress is system int
    nStringAddress = CallDLL32(<DLL>, <Function>)
    sString is string
    sString = StringRetrieve(nStringAddress, srASCIIZAddress)
    // in Method in C: Return PointerInC

Passing a structure containing a string to an API

  1. In input, the following code must be used:
    Struct is structure
    sString is string
    END
    AStruct is Struct
    CallDLL32(<DLL>, <Function>, &AStruct)
  2. In output, the C language does not easily manage the dynamic strings. Therefore, you must:
    • define a maximum size and perform a copy into the WLanguage memory. For example:
      sString is string on 100
      Struct is structure
      aString is int
      END
      AStruct is Struct
      AStruct:aString = &sString
      CallDLL32(<DLL>, <Function>, &AStruct)
      // in Method in C:
      // STRNCPY(CStruct->PointerInC, "Test", 100)
    • retrieve the address of strings in C (however, in this case, the code section in C must "preserve " the strings returned). For example:
      sString is string
      Struct is structure
      aString is int
      END
      AStruct is Struct
      CallDLL32(<DLL>, <Function>, &AStruct)
      sString = StringRetrieve(AStruct:aString, srASCIIZAddress)
      // in Method in C: StructInC->PointerInC = "Test"

Procedure called in CallBack

Some functions of the Windows API expect the address of a "CallBack" procedure as parameter: this procedure will be called back by the function of the API.
For example: the EnumWindows API is used to list all the Windows windows opened on a computer. This function expects the address of a procedure as parameter: this procedure will be called whenever a window is found.
Versions 16 and later
Remark: The CallBack procedures can be used in 32 bits and in 64 bits.
New in version 16
Remark: The CallBack procedures can be used in 32 bits and in 64 bits.
Remark: The CallBack procedures can be used in 32 bits and in 64 bits.
To use a callback procedure in WLanguage:
1. Create the callback procedure in your project.
To retrieve the parameters, you must exactly describe the parameters expected by the "CallBack" function. Otherwise, "general protection faults" may occur.
PROCEDURE <Procedure name> (<Param1> is <Type1>,<Param2> is <Type2>)
Remarks:
  • The types must correspond to the ones described in the documentation of the API.
  • The type of the "CallBack" function of the DLL must be "stdcall".
  • The parameters must necessarily be passed by value. To retrieve a parameter by reference:
    1. Use an integer.
    2. With Transfer, retrieve or assign the real value.
2. Modify the call to the function accordingly. Use the following syntax:
CallDLL32(<DLL name>, <Function name>, <Name of callback procedure>)
See the full example for more details.

Miscellaneous

  • API and CallDLL32 do not lock the other threads.
  • If the API function called modifies the system regional settings, the previous regional settings are restored.
APIParameter is used to configure the default behavior of these functions.
Remark: up to version 100045:
  • API and CallDLL32 lock the other threads.
  • If the API function called modifies the system regional settings (languages, decimal places, etc.), the previous regional settings are not restored.
Related Examples:
Strings with APIs Unit examples (WINDEV): Strings with APIs
[ + ] Using strings with APIs.
The following functions are used:
- StringRetrieve
- Transfer
WD SystemAPIs Training (WINDEV): WD SystemAPIs
[ + ] This example presents the use of the Windows APIs. Several WLanguage functions are used to perform the following operations:

- Hide the system buttons of an MDI child window
- Enumerate the opened windows
- Retrieve/Modify the time of a double click
- Retrieve the idle time on the computer
- Empty the recycle bin (by using or not an "API descriptor" variable)
- Change the screen background
- Modify the caret (input cursor) of an edit control
- Share a directory
- Delete a share

These functions use the Windows APIs. See the help window for more details.
WD Screen Saver Training (WINDEV): WD Screen Saver
[ + ] This example illustrates the creation of a screen saver with the WLanguage functions.
The following topics are presented in this example:
1/ the periodic call to a procedure ("timers")
2/ the management of Windows events
3/ the system functions (call to Windows APIs)
To use the screen saver:
- Rename the executable (.EXE) to.SCR
- Copy the file to the directory of Windows (Ex: C:\WINDOWS)
- Open the window for the display properties of the desktop
- Choose the "Screen Saver" tab
- Select the screen saver generated by WINDEV
WD DirectX Training (WINDEV): WD DirectX
[ + ] DirectX is a set of libraries (or APIs) intended for programming multimedia applications.
This example includes an internal component allowing you to use DirectX 9.0 in your WINDEV applications.
All the APIs and interfaces of DirectX 9 have been implemented.
Component: wd270vm.dll
Minimum version required
  • Version 9
This page is also available for…
Comments
Click [Add] to post a comment