IDLcomIDispatch

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.

; Create a IDLcomIDispatch object from a class identifier {A77BC2B2-88EC-4D2A-B2B3-F556ACB52E52}

obj = Obj_New('IDLcomIDispatch$CLSID$A77BC2B2_88EC_4D2A_B2B3_F556ACB52E52')

 

; Create a IDLcomIDispatch object from a program identifier "RSIDemoComponent.RSIDemoObj1.1"

obj = Obj_New('IDLcomIDispatch$PROGID$RSIDemoComponent_RSIDemoObj1_1')

 

; Set and get a property called MessageStr

obj.SetProperty, MESSAGESTR='my message'

obj.GetProperty, MESSAGESTR=msg

 

; Call a method on the COM object with the name GetCLSID

result = obj.GetCLSID( )

print, result

 

; Call a method named Msg2InParams which takes 2 input args and contatenates them

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:

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 ; print the altered array after call

The IDL array must be large enough for the client's use. On the COM side:

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.