PC SOFT

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Home | Sign in | English US
  • Checks performed
  • Managing the 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 to an API
  • Passing a structure containing a string to an API
  • Procedure called in CallBack
  • Various
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadApple WatchUniversal Windows 10 AppWindows Mobile
Others
Stored procedures
Runs a function found in an external DLL. This function can be a function of Windows API. The functions accessible by API 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
You also have the ability to use an API Description variable. For the APIs called several times in the same application or that use some parameters of specific types, we recommend that you use an API Description variable with direct use (without calling API).
New in version 16
You also have the ability to use an API Description variable. For the APIs called several times in the same application or that use some parameters of specific types, we recommend that you use an API Description variable with direct use (without calling API).
You also have the ability to use an API Description variable. For the APIs called several times in the same application or that use some parameters of specific types, we recommend that you use an API Description variable with direct use (without calling API).
Notes:
  • This function is equivalent to CallDLL32.
  • 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).
API("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> = API(<DLL Name> , <Function Name> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<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. See the documentation about this function for more details.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<DLL Name>: Character string (with quotes)
Name of library (DLL) containing the function to run.
<Function Name>: Character string (with quotes)
Name of 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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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> = API(<DLL Name>, <Function Number> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<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. See the documentation about this function for more details.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<DLL Name>: Character string (with quotes)
Name of library (DLL) containing the function to run.
<Function Number>: Integer
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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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> = API(<Function Address> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<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. See the documentation about this function for more details.
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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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> = API(<Function Address> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<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. See the documentation about this function for more details.
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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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> = API(<Function Address> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<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. See the documentation about this function for more details.
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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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 an API Description variable Hide the details

<Result> = API(<API to Run> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <API to Run>. This result can be an error code. The type of this result depends on the function run. See the documentation about this function for more details.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<API to Run>: API Description variable
API Description variable containing the characteristics 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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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 an API Description variable Hide the details

<Result> = API(<API to Run> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <API to Run>. This result can be an error code. The type of this result depends on the function run. See the documentation about this function for more details.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<API to Run>: API Description variable
API Description variable containing the characteristics 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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • 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 an API Description variable Hide the details

<Result> = API(<API to Run> [, <Parameter 1> [, <Parameter 2> [, ...]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of execution of <API to Run>. This result can be an error code. The type of this result depends on the function run. See the documentation about this function for more details.
The function result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<API to Run>: API Description variable
API Description variable containing the characteristics 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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
<Parameter 2>: Type corresponding to the parameter
Second 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 Remarks),
  • the structures (see Remarks),
  • a name of WLanguage procedure. This procedure will be called by the function of DLL (see Remarks).
Remarks

Checks performed

  • API 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 the 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

API 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
    API(<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
      API(<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
      API(<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 = API(<DLL>, <Function>)
    sString is string
    sString = StringRetrieve(nStringAddress, srASCIIZAddress)
    // in Method in C: Return PointerInC

Passing a structure to an API

The structures can be directly passed in parameter to the APIs, without going via their address. To do so, the members of the structure must be passed in parameter one by one.
Limit: All the members of the structure must be aligned on 4 bytes.

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
    API(<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
      API(<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
      API(<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 in 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 in parameter: this procedure will be called whenever a window is found.
Versions 16 and later
Note: The CallBack procedures can be used in 32 bits and in 64 bits.
New in version 16
Note: The CallBack procedures can be used in 32 bits and in 64 bits.
Note: 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>)
Notes:
  • The types must correspond to the ones described in the documentation of the API.
  • Versions 18 and later
    The call convention of the DLL "CallBack" functions must be "stdcall" or "cdecl". By default, the call convention is considered as being "stdcall". A "cdecl" callback can be declared via the "call convention" attribute. The prototype of the function becomes:
    PROCEDURE <Procedure Name> (<Param1> is <Type1>, ...
    <Param2> is <Type2>) <call convention=CDECL>
    New in version 18
    The call convention of the DLL "CallBack" functions must be "stdcall" or "cdecl". By default, the call convention is considered as being "stdcall". A "cdecl" callback can be declared via the "call convention" attribute. The prototype of the function becomes:
    PROCEDURE <Procedure Name> (<Param1> is <Type1>, ...
    <Param2> is <Type2>) <call convention=CDECL>
    The call convention of the DLL "CallBack" functions must be "stdcall" or "cdecl". By default, the call convention is considered as being "stdcall". A "cdecl" callback can be declared via the "call convention" attribute. The prototype of the function becomes:
    PROCEDURE <Procedure Name> (<Param1> is <Type1>, ...
    <Param2> is <Type2>) <call convention=CDECL>
  • The parameters must necessarily be passed by value. To retrieve a parameter by address:
    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:
API(<DLL Name>, <Function Name>, <Name of Callback Procedure>)
See the full example for more details.

Various

  • 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.
Note: Up to version 100045:
  • API and CallDLL32 lock the other threads.
  • If the API function called modifies the system regional settings (languages, decimal places, ...), 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.
WD OSD Training (WINDEV): WD OSD
[ + ] OSD means: On-Screen Display. This is the name given to the interfaces that appear on the computer screens or on the TV screens for example. They are used to perform settings in most cases.
These types of menus are displayed above all the other elements found on the screen.
This example explains how to create this type of interface in WINDEV.
WD Magnifier Complete examples (WINDEV): WD Magnifier
[ + ] This example enables you to zoom part of the screen with a magnifier.
The maximum zoom value is set to 8.
Summary of the example supplied with WINDEV:
The WLanguge function named dCopyBlt() and the WLanguage property named ..Opacity allow you to perform a capture of the Windows desktop at the location of a window without this window appearing in the screen shot.
This example uses this tip to zoom the part of the screen found below the magnifier.
Components
WINDEVWEBDEV - Server codeReports and Queries wd230vm.dll
Linux wd230vm.so
Windows Mobile wp230vm.dll
Minimum required version
  • Version 9
This page is also available for…
Comments
Click [Add] to post a comment