PC SOFT

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Home | Sign in | English US
  • Checks performed
  • Managing the errors
  • Parameters that must be passed to the method of DLL
  • Passing a string to a DLL or retrieving a string from a DLL
  • Passing a structure containing a string to a DLL
  • 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
CallInterface (Function)
In French: AppelInterface
Runs a method of an interface of an object implemented in a DLL external to the WINDEV framework. This object can be a C++ object or a COM object.
Versions 15 and later
Windows Mobile This function is now available for the Windows Mobile applications.
New in version 15
Windows Mobile This function is now available for the Windows Mobile applications.
Windows Mobile This function is now available for the Windows Mobile applications.
Versions 21 and later
WINDEVLinux This function is now available for the WINDEV applications in Linux.
WEBDEV - Server codeLinux This function is now available for the WEBDEV sites in Linux.
New in version 21
WINDEVLinux This function is now available for the WINDEV applications in Linux.
WEBDEV - Server codeLinux This function is now available for the WEBDEV sites in Linux.
WINDEVLinux This function is now available for the WINDEV applications in Linux.
WEBDEV - Server codeLinux This function is now available for the WEBDEV sites in Linux.
Example
nAllocator is system int
API("ole32", "CoGetMalloc", 1, &nAllocator)
nMemory is system int = CallInterface(nAllocator, 3, 1024)
Syntax

Using the method number Hide the details

<Result> = CallInterface(<Object Address> , <Method Number> [, <Parameter 1> [, <Parameter 2> [ , ... ]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of method execution. This result can be an error code. The type of this result depends on the method run. See the documentation about the method for more details.
The method result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Object Address>: System integer
Address of object onto which a method will be called. In most cases, this address is the result of the previous call to an API.
<Method Number>: Integer
Order number of method in the table of virtual methods.
CAUTION:
  • the order number takes the base classes into account
  • the order number starts from 0.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by the method (see the Notes).
<Parameter 2>: Type corresponding to the parameter
Second parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by method (see the Notes).
Versions 16 and later

Using an API Description variable Hide the details

<Result> = CallInterface(<Object Address> , <API to Run> [, <Parameter 1> [, <Parameter 2> [ , ... ]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of method execution. This result can be an error code. The type of this result depends on the method run. See the documentation about the method for more details.
The method result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Object Address>: System integer
Address of object onto which a method will be called. In most cases, this address is the result of the previous call to an API.
<API to Run>: API Description variable
API description variable containing the characteristics of method to run.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by the method (see the Notes).
<Parameter 2>: Type corresponding to the parameter
Second parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by method (see the Notes).
New in version 16

Using an API Description variable Hide the details

<Result> = CallInterface(<Object Address> , <API to Run> [, <Parameter 1> [, <Parameter 2> [ , ... ]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of method execution. This result can be an error code. The type of this result depends on the method run. See the documentation about the method for more details.
The method result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Object Address>: System integer
Address of object onto which a method will be called. In most cases, this address is the result of the previous call to an API.
<API to Run>: API Description variable
API description variable containing the characteristics of method to run.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by the method (see the Notes).
<Parameter 2>: Type corresponding to the parameter
Second parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by method (see the Notes).

Using an API Description variable Hide the details

<Result> = CallInterface(<Object Address> , <API to Run> [, <Parameter 1> [, <Parameter 2> [ , ... ]]])
<Result>: 4-byte integer in 32 bits, 8-byte integer in 64 bits
Result of method execution. This result can be an error code. The type of this result depends on the method run. See the documentation about the method for more details.
The method result will not be retrieved if its size exceeds the size of the integer defined for the platform.
<Object Address>: System integer
Address of object onto which a method will be called. In most cases, this address is the result of the previous call to an API.
<API to Run>: API Description variable
API description variable containing the characteristics of method to run.
<Parameter 1>: Type corresponding to the parameter
First parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by the method (see the Notes).
<Parameter 2>: Type corresponding to the parameter
Second parameter that will be passed to the method. These parameters and the parameters expected by the method must have the same type. Can be used:
  • the "simple" types (see the Notes),
  • the structures (see the Notes),
  • a name of WLanguage procedure. This procedure will be called by method (see the Notes).
Remarks

Checks performed

CallInterface is protected against the "General protection faults" in the method called. Nevertheless, a WLanguage error is triggered if this type of error occurs.

Managing the errors

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

Parameters that must be passed to the method of DLL

These parameters and the parameters expected by the method must have the same type.
The available types are as follows:
  • The "simple" types (integer, real and boolean). Using another WLanguage type triggers a WLanguage error.
    If the method to run expects a Windows pointer or handle, use a system integer.
    If the method 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 method of the DLL (see the paragraph below).
    The parameters depend on the method run. See the documentation about this method for more details.

Passing a string to a DLL or retrieving a string from a DLL

  1. In input parameter, use the string type. For example:
    sString is string
    CallInterface(<Object Address>, <Method Number>, 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
      CallInterface(<Object Address>, <Method Number>, 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(<Object Address>, <Method Number>, &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 = CallInterface(<Object Address>, <Method Number>)
    sString is string
    sString = StringRetrieve(nStringAddress, srASCIIZAddress)
    // in Method in C: Return PointerInC

Passing a structure containing a string to a DLL

  1. In input, the following code must be used:
    Struct is structure
    sString is string
    END
    AStruct is Struct
    CallInterface(<Object address>, <Method number>, &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
      CallInterface(<Object address>, <Method number>, &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
      CallInterface(<Object address>, <Method number>, &AStruct)
      sString = StringRetrieve(AStruct:aString, srASCIIZAddress )
      // in Method in C: StructInC->PointerInC = "Test"

Procedure called in CallBack

Some methods expect the address of a "Callback" procedure in parameter: this procedure will be called back by the DLL method.
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 DLL.
  • 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 method accordingly. Use the following syntax:
CallInterface(<Object Address>, <Method Number>, ...
&<Name of CallBack Procedure>)
Reports and QueriesWindowsUser code (UMC)

Various

  • CallInterface does not lock the other threads.
  • If the method of the DLL called modifies the system regional settings, the previous regional settings are restored.
APIParameter is used to configure the default behavior of this function.
Components
WINDEVWEBDEV - Server codeReports and Queries wd230vm.dll
Windows Mobile wp230vm.dll
Linux wd230vm.so
Minimum required version
  • Version 11
This page is also available for…
Comments
Click [Add] to post a comment