ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Standard functions / Windows functions / Miscellaneous Windows functions
  • Using the API Description variables
  • Properties specific to API Description variables
  • Special cases
  • Functions that use API Description variables
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
API description (Type of variable)
In french: Description d'API
An API Description variable is used to describe an API, its parameters, its return value and its calling options through programming.
The characteristics of this type can be defined and changed using different WLanguage properties.
Remark: For more details on the declaration of this type of variable and the use of WLanguage properties, see Declaring a variable.
Example
GetModuleHandle is API Description
GetModuleHandle.DLLName = "kernel32"
GetModuleHandle.FunctionName = "GetModuleHandleA"
GetModuleHandle.ReturnType = apiSystemInt
GetModuleHandle.Parameter[1].Type = apiAnsiString
// Call a fictitious DLL for calculating the distance between 2 points on the surface of the Earth
CalculateDistance is API Description
CalculateDistance.DLLName = "GEO.DLL"
CalculateDistance.FunctionName = "CalculateDistance"
CalculateDistance.Parameter[1].Type = apiReal_8
CalculateDistance.Parameter[2].Type = apiReal_8
CalculateDistance.Parameter[3].Type = apiReal_8
CalculateDistance.Parameter[4].Type = apiReal_8
CalculateDistance.ReturnType = apiReal_8
 
distance is real = CalculateDistance(Latitude1, Longitude1, Latitude2, Longitude2)
Remarks

Using the API Description variables

The API description variables can be used:
  • directly, by specifying the values of the different parameters if necessary. For example:
    GetModuleHandle is API Description
    GetModuleHandle.DLLName = "kernel32"
    GetModuleHandle.FunctionName = "GetModuleHandleA"
    GetModuleHandle.ReturnType = apiSystemInt
    GetModuleHandle.Parameter[1].Type = apiAnsiString
     
    // Direct use
    GetModuleHandle(Null)
  • with the API function. For example:
    GetModuleHandle is API Description
    GetModuleHandle.DLLName = "kernel32"
    GetModuleHandle.FunctionName = "GetModuleHandleA"
    GetModuleHandle.ReturnType = apiSystemInt
    GetModuleHandle.Parameter[1].Type = apiAnsiString
     
    // Use of the API function
    API(GetModuleHandle, Null)

Properties specific to API Description variables

The following properties can be used to handle an API Description:
Property nameType usedEffect
AddressSystem integerAddress of the function.
If a value is assigned to this property, the FunctionName property contains the address of the function, the Number property is set to -1 and the DLLName property is set to "" (empty string).
CallingConventionInteger constantMethod for calling the DLL. Three call conventions are available via the following constants:
  • CDECL
  • STDCALL
  • THISCALL
DLLNameCharacter stringDLL name.
FunctionNameCharacter stringName of the function found in the DLL.
If this property is specified, the DLLName property must also be specified. In this case, the Number property is set to -1 and the Address property is set to 0.
NumberIntegerNumber of the function.
If this property is specified, the DLLName property must also be specified. In this case, the FunctionName property contains the number and Address is reset to 0.
OptionInteger constantOptions for calling the API. This property can correspond to one of the following constants:
  • apiLockThreads: If this constant is used, the call to the API locks all the current threads. This is used to protect the external DLL from the multi-thread calls.
  • apiFreeDLL: If the DLL was loaded to call the API, it will be unloaded. This constant is ignored if the DLL was already loaded during the call to the API.
  • apiRestoreSystemSettings: If this constant is used, the system parameters will be restored after the call to the API. Indeed, some APIs modify the system parameters.
The default options are apiRestoreSystemSettings + apiFreeDLL.
ParameterArrayThe Type property of each element of the array indicates the type of each API parameter. This property can correspond to:
  • a structure name in string form if the parameter is a structure passed as a parameter by value,
  • one of the following constants:
    • apiBoolean: the parameter is a boolean.
    • apiBuffer: the parameter is a buffer.
    • apiCharacter: the parameter is an Ansi character if the project is in Ansi mode, the parameter is a Unicode character if the project is in Unicode mode.
    • apiAnsiCharacter: the parameter is an Ansi character.
    • apiUnicodeCharacter: the parameter is a Unicode character
    • apiString: the parameter is an Ansi character string if the project is in Ansi mode, the parameter is a Unicode character string if the project is in Unicode mode.
    • apiAnsiString: the parameter is an Ansi character string.
    • apiUnicodeString: the parameter is a Unicode character string.
    • apiInt_1: the parameter is a 1-byte integer.
    • apiInt_2: the parameter is a 2-byte integer.
    • apiInt_4: the parameter is a 4-byte integer.
    • apiInt_8: the parameter is an 8-byte integer.
    • apiUnsignedInt_1: the parameter is an unsigned 1-byte integer.
    • apiUnsignedInt_2: the parameter is an unsigned 2-byte integer.
    • apiUnsignedInt_4: the parameter is an unsigned 4-byte integer.
    • apiUnsignedInt_8: the parameter is an unsigned 8-byte integer.
    • apiSystemInt: the parameter is a system integer.
    • apiReal_4: the parameter is a 4-byte real.
    • apiReal_8: the parameter is a 8.-byte real
ReturnTypeInteger or stringType returned by the API. This property corresponds to:
  • apiBoolean: the API returns a boolean.
  • apiBuffer: the API returns a buffer.
  • apiCharacter: the API returns an Ansi character if the project is in Ansi mode, a Unicode character if the project is in Unicode mode.
  • apiAnsiCharacter: the API returns an Ansi character.
  • apiUnicodeCharacter: the API returns a Unicode character.
  • apiString: the API returns an Ansi character string if the project is in Ansi mode, a Unicode character string if the project is in Unicode mode.
  • apiAnsiString: the API returns an Ansi character string.
  • apiUnicodeString: the API returns a Unicode character string.
    • apiInt_1: the API returns a 1-byte integer.
    • apiInt_2: the API returns a 2-byte integer.
    • apiInt_4: the API returns a 4-byte integer.
    • apiInt_8: the API returns an 8-byte integer.
    • apiUnsignedInt_1: the API returns a 1-byte integer.
    • apiUnsignedInt_2: the API returns a 2-byte integer.
    • apiUnsignedInt_4: the API returns a 4-byte integer.
    • apiUnsignedInt_8: the API returns an 8-byte integer. * apiSystemInt: the API returns a system integer.
  • apiReal_4: the API returns a 4-byte real.
  • apiReal_8: the API returns a 8.-byte real

Special cases

  • An API Description variable must be declared for each function used.
  • The DLL is loaded once only, and not for each variable.

Functions that use API Description variables

The following functions can be used to handle API Description variables:
APIRuns a function found in an external DLL.
CallDLL32Runs a function found in an external DLL.
Minimum version required
  • Version 16
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 01/26/2023

Send a report | Local help