ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Standard functions / Windows functions / Miscellaneous Windows functions
  • Checks performed
  • Handling errors
  • Parameters that must be passed to the method of the COM object
  • Passing a string to a method of COM object or retrieving a string after the call to a method of COM object
  • Passing a structure containing a string to a method of COM object
  • 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
Runs a method of an interface of a COM object instantiated by COMCreateInstance.
Example
// Initialize a Unicode string containing 260 characters
WallPaper is UNICODE string
WallPaper = AnsiToUnicode(RepeatString(" ", 260))

// Declare a COMObject variable
ActiveDesktop is COMObject

// Retrieve the interface for handling the desktop
ActiveDesktop = COMCreateInstance("75048700-EF1F-11D0-9888-006097DEACF9", ...
"F490EB00-1240-11D1-9888-006097DEACF9")
IF ErrorOccurred = False THEN
// Retrieve the image of the desktop wallpaper
COMCallMethod(ActiveDesktop, 4, &WallPaper, 260, 1)

Info("The image of the desktop is: " + UnicodeToAnsi(WallPaper))
END
Syntax

Using the method number Hide the details

<Result> = COMCallMethod(<COM Object> , <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.
<COM Object>: COMObject variable
Interface of COM object returned by COMCreateInstance.
<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 Notes).
<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 the method (see the Notes).

Using an API Description variable Hide the details

<Result> = COMCallMethod(<COM Object> , <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.
<COM Object>: COMObject variable
Interface of COM object returned by COMCreateInstance.
<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 Notes).
<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 a method (see Notes).
Remarks

Checks performed

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

Handling 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 the COM object

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 COM object (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 method of COM object or retrieving a string after the call to a method of COM object

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

Passing a structure containing a string to a method of COM object

  1. In input, the following code must be used:
    Struct is structure
    sString is string
    END
    AStruct is Struct
    COMCallMethod(<Object>, <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
      COMCallMethod(<Object>, <Method number>, &AStruct)
      // in Method in C:
      // strncpy(StructInC->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
      COMCallMethod(<Object>, <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 recalled by the method of the COM object.
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 COM object.
  • 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:
COMCallMethod(<Object>, <Method number>, &<Name of CallBack procedure>)
WINDEVWEBDEV - Server codeReports and QueriesWindowsUser code (UMC)

Miscellaneous

  • COMCallMethod does not block other threads.
  • If the method called modifies the regional system parameters, the previous regional parameters are restored.
APIConfigure is used to configure the default behavior of this function.
Component: wd290vm.dll
Minimum version required
  • Version 15
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 12/20/2023

Send a report | Local help