ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Standard functions / Windows functions / Miscellaneous Windows functions
  • 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
  • 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
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.
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 N>]]])
<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. For more details, see the documentation about the method.
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 Remarks),
  • the structures (see the Remarks),
  • a name of WLanguage procedure. This procedure will be called by the method (see the Remarks).
<Parameter N>: Type corresponding to the parameter
Nth 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 Remarks),
  • the structures (see the Remarks),
  • a name of WLanguage procedure. This procedure will be called by method (see the Remarks).

Using an API Description variable Hide the details

<Result> = CallInterface(<Object address> , <API to run> [, <Parameter 1> [... [, <Parameter N>]]])
<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. For more details, see the documentation about the method.
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 the method to be 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 Remarks),
  • the structures (see the Remarks),
  • a name of WLanguage procedure. This procedure will be called by the method (see the Remarks).
<Parameter N>: Type corresponding to the parameter
Nth 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 Remarks),
  • the structures (see the Remarks),
  • a name of WLanguage procedure. This procedure will be called by method (see the Remarks).
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 get more details on the error.

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. For more details, see the documentation about this method.

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 as 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>)
Remarks:
  • 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 reference:
    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)

Miscellaneous

  • CallInterface does not block 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.
Component: wd290vm.dll
Minimum version required
  • Version 11
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 05/26/2022

Send a report | Local help