The IDLcomIDispatch object class creates an IDL object that encapsulates a COM object. IDL provides data type and other translation services, allowing IDL programs to access the COM object’s methods and properties using standard IDL syntax.
See IDL Feature Support for a list of platforms that support IDLcomIDispatch.
Note: COM objects encapsulated by IDLcomIDispatch objects must implement an IDispatch interface.
Note: You should be aware that COM, like C, stores array data in row-major format. IDL stores array data in column-major format.
Note: Microsoft has been slowly deprecating the IDispatch interface - IDL will continue to support this interface for as long as Microsoft continues to make it available.
Examples
Note: The examples below demonstrate how to use the API, but will not actually run. You will need to write your own code for your desired COM object.
obj = Obj_New('IDLcomIDispatch$CLSID$A77BC2B2_88EC_4D2A_B2B3_F556ACB52E52')
obj = Obj_New('IDLcomIDispatch$PROGID$RSIDemoComponent_RSIDemoObj1_1')
obj.SetProperty, MESSAGESTR='my message'
obj.GetProperty, MESSAGESTR=msg
result = obj.GetCLSID( )
print, result
result = obj.Msg2InParams("The value is: ", 25.0)
print, result
Methods
Other Information
IDLcomIDispatch::Init
The IDLcomIDispatch::Init function method is used to initialize a given COM object and establish a link between the resulting IDL object and the IDispatch interface of the underlying COM object.
Syntax
Obj = OBJ_NEW(Classname)
Return Value
The result is an IDL object reference that links to the COM object.
Arguments
Classname
The class name must have the following form: "IDLcomIDispatch$Type$ID", where:
Type is one of the following:
-
CLSID if the object is identified by its COM class ID, or
-
PROGID if the object is identified by its COM program ID
ID is the COM object’s actual class or program identifier string.
Tip: If the COM object’s class identifier string is used to create the IDLcomIDispatch object, the braces { } must be removed and all hyphens must be replaced by underscores. If the program identifier string is used, then you must replace all dot characters with underscores. See examples above.
Keywords
None
IDLcomIDispatch::GetProperty
The IDLcomIDispatch::GetProperty method is used to get properties from the COM object. The COM object’s property names are represented as IDL arguments or keywords to the GetProperty method.
Syntax
Obj.GetProperty [, arg0, arg1,…] [, PROPERTYNAME=variable]
Arguments
ARG0, ARG1, ...
Because some of the underlying COM object’s property methods may require arguments, the GetProperty method will accept optional arguments. The values of the arguments themselves will depend on the COM object that underlies the IDLcomIDispatch object.
Note: If arguments are required, you can only specify one property to retrieve in a given call to GetProperty.
Keywords
PROPERTYNAME
PROPERTYNAME must match the name of one of the underlying COM object’s properties, and variable is the name of an IDL variable that will contain the retrieved property value. You can get multiple property values in a single statement by supplying multiple PROPERTYNAME=variable pairs.
Note: PROPERTYNAME must map exactly to the full name of the underlying COM object’s property.
Tip: It is common for COM objects to return references to other COM objects, either as a property value or via an object method. In this case, IDL will automatically create an IDLcomIDispatch object to contain the object reference. You can then use this returned object just like any other IDLcomIDispatch object.
IDLcomIDispatch::SetProperty
The IDLcomIDispatch::SetProperty method is used to set properties on the COM object. The COM object’s property names are represented as keywords to the SetProperty method.
Syntax
Obj.SetProperty [, arg0, arg1,…] [, PROPERTYNAME=value]
Arguments
ARG0, ARG1, ...
Because the underlying COM object’s propput method may require parameters, the SetProperty method will accept optional arguments. The values of the parameters themselves will depend on the COM object that underlies the IDLcomIDispatch object.
Keywords
PROPERTYNAME
PROPERTYNAME must match the name of one of the underlying COM object’s properties, and value is an IDL variable that contains the property value to set. You can set multiple property values in a single statement by supplying multiple PROPERTYNAME=value pairs.
Note: PROPERTYNAME must map exactly to the full name of the underlying COM object’s property.
If you pass parameters when setting multiple properties, the parameter or parameters are sent to each property being set. For example:
obj.SetProperty, 'Parm1', 24L, oRef, OPTION=1, INDEX=99L
This command is equivalent to the following lines:
obj.SetProperty, 'Parm1', 24L, oRef, OPTION=1
obj.SetProperty, 'Parm1', 24L, oRef, INDEX=99L
Thus, when you are setting multiple properties at the same time and passing parameters, all the properties that are set at the same time must be defined as receiving the same sets of parameters.
IDLcomIDispatch::CustomMethod
The IDLcomIDispatch class automatically wraps all of the underlying COM object's methods. These can be called as custom methods on the IDLcomIDispatch object using IDL's standard object method syntax.
Note: The IDLcomIDispatch class implements the following methods: Init, Cleanup, GetProperty, and SetProperty. If the COM object underlying an IDLcomIDispatch object implements methods with these same names, they will be overridden by IDL’s methods — the COM object’s methods will be inaccessible from IDL.
Syntax
Obj.MethodName [, Arg0, Arg1, ...] [, SKIP=value]
or
result = Obj.MethodName([Arg0, Arg1, ... )
Note: In COM, all object methods are functions. IDL’s implementation of the IDLcomIDispatch object maps COM methods that supply a return value using the retval attribute as IDL functions, and COM methods that do not supply a return value as procedures.
Result
For function methods, the result will be an IDL variable containing the result value.
Tip: It is common for COM objects to return references to other COM objects, either as a property value or via an object method. In this case, IDL will automatically create an IDLcomIDispatch object to contain the object reference. You can then use this returned object just like any other IDLcomIDispatch object.
Arguments
ARG0, ARG1, ...
Set these arguments to the values to be passed into the underlying COM object.
Keywords
SKIP
COM allows methods with optional arguments to accept a subset of the full argument list by specifying which arguments are not present. This allows the calling routine to supply, for example, the first and third arguments to a method, but not the second. To skip one or more arguments from a list of optional arguments, set the SKIP keyword to either a scalar or a vector of numbers specifying which arguments are not provided.
For example, suppose a COM object method accepts four arguments, of which the second, third, and fourth are optional:
MyMethod, arg1, arg2-optional, arg3-optional, arg4-optional
To call this method on the IDLcomIDispatch object, passing in values for arguments 1, 3, and 4, but skipping argument 2, use the following command:
obj.MyMethod, arg1, arg3, arg4, SKIP=1
Similarly, to skip arguments 2 and 3, use the following command:
obj.MyMethod, arg1, arg4, SKIP=[1,2]
Finally, note that you do not need to supply the SKIP keyword if the arguments are supplied in order. For example, to skip arguments 3 and 4:
obj.MyMethod, arg1, arg2
COM-IDL Data Type Mapping
When data moves from IDL to a COM object and back, IDL handles conversion of variable data types automatically, using the following conversion rules:
|
COM Type |
IDL Type |
|
BOOL (VT_BOOL) |
Byte (0 or 1) |
|
ERROR (VT_ERROR)
|
Long |
| CY (VT_CY) |
Double* |
| DATE (VT_DATE) |
Double |
| I1 (VT_I1) |
Byte |
| INT (VT_INT) |
Long |
| UINT (VT_UINT) |
Unsigned Long |
| VT_USERDEFINED |
IDL type is passed through
|
| VT_UI1 |
Byte |
| VT_I2 |
Integer |
| VT_UI2 |
Unsigned Integer |
| VT_ERROR |
Long |
| VT_I4 |
Long |
| VT_UI4 |
Unsigned Long |
| VT_I8 |
Long64 |
| VT_UI8 |
Unsigned Long64 |
| VT_R4 |
Float |
| VT_BSTR |
String |
| VT_R8 |
Double |
| VT_DISPATCH |
IDLcomIDispatch |
| VT_UNKNOWN |
IDLcomIDispatch |
* The COM CY data type is a scaled 64-bit integer, supporting exactly four digits to the right of the decimal point. To provide an easy-to-use interface, IDL automatically scales the integer as part of the data conversion that takes place between COM and IDL, allowing the IDL user to treat the number as a double-precision floating-point value. When the value is passed back to the COM object, it will be truncated if there are more than four significant digits to the right of the decimal point. For example, the IDL double-precision value 234.56789 would be passed to the COM object as 234.5678.
Pass Arrays by Reference
By default, IDL arrays are passed to and received from the COM subsystem "by value", meaning that the array is copied. When dealing with large arrays, performance may suffer. Instead, you can pass arrays "by reference". To pass an array by reference, you can define an IDL pointer to the array. In this case, passing the pointer to a COM object will automatically pass by reference. For example:
myarr = findgen(10)
myptr = ptr_new(myarr, /no_copy)
obj.CallMyComMethod, myptr
print, *myptr
The IDL array must be large enough for the client's use. On the COM side:
-
The COM object cannot resize the array (although the COM object does not have to use or set all the elements in the array)
-
The COM object cannot change the type of the elements
-
The COM object cannot change the dimensionality of the array. For multidimensional arrays, IDL must define the source array with the same dimensions as the COM client expects.
Note: You cannot pass arrays by reference if the arrays contain strings, object references, IDL pointers, or IDL structures.
Version History
|
5.5 |
Introduced |
| 8.9 |
Removed 32-bit Windows support
|
| 9.1 |
Restored missing documentation. |