API description (Type of variable)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

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

WEBDEV

WINDEV Mobile

Others

See also

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 name	Type used	Effect

Address	System integer	Address 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).
CallingConvention	Integer constant	Method for calling the DLL. Three call conventions are available via the following constants: CDECL STDCALL THISCALL
DLLName	Character string	DLL name.
FunctionName	Character string	Name 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.
Number	Integer	Number 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.
Option	Integer constant	Options 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.
Parameter	Array	The 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
ReturnType	Integer or string	Type 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:


API	Runs a function found in an external DLL.
CallDLL32	Runs a function found in an external DLL.