1.9 Calling COM object methods from Lisp

Within the implementation of a COM object, the macros call-com-object and with-com-object can be used to call COM methods directly for a COM object without using an interface pointer. To call a COM method, you need to specify the class name, the method name, the interface name if the method name is not unique, a COM object and suitable arguments. The class name is a symbol as used in the define-com-implementation form and can be a superclass of the actual object class. The method and interface names are given as symbols named as in The mapping from COM names to Lisp symbols. and the arguments and values are as specified below in Data conversion when calling COM object methods. These macros should be used with caution because they assume that the caller knows the implementation's pass-style for all the arguments.

The with-com-object macro is useful when several methods are being called with the same COM object, because it establishes a local macro that takes just the method name and arguments.

1.9.1 Data conversion when calling COM object methods

No explicit argument or return value conversion is done by call-com-object or with-com-object. As a result, every argument must be passed as a positional argument and must be of the type expected by the method's implementation The allowable types are described in the following sections.

1.9.1.1 In parameters

For in parameters,

For a parameter with the string attribute, the value can be a Lisp string.
For a parameter of COM type BSTR, the value can be a Lisp string.
For a parameter whose type is an array type or a pointer type with a size_is attribute, the value can be a Lisp array of the appropriate rank and dimension.
Otherwise, the value should match what the FLI would generate for the parameter's type.

1.9.1.2 Out parameters

For out parameters,

If nil is passed, the value from the method is returned without any conversion.
For a parameter whose type is an array type or a pointer type with a size_is attribute, the value can be a Lisp array. The contents of the array will be modified by the method and the array will be returned as a value.
Otherwise, the value should be a foreign pointer of the type that the FLI would generate for the parameter's type. The foreign pointer will be returned as a value.

1.9.1.3 In-out parameters

For in-out parameters,

For a parameter whose type is an array type or a pointer type with a size_is attribute, the value can be a Lisp array. The contents of the array will be modified by the method and the array will be returned as a value.
For a parameter with the string attribute, the parameter can be a Lisp string. The value of the parameter at the end of the body will be returned as a value.
For a parameter of COM type BSTR*, the parameter can be a Lisp string. The value of the parameter at the end of the body will be returned as a value.
For parameters of COM type VARIANT*, the parameter can be any Lisp object. The value of the parameter at the end of the body will be returned as a value.
If the value is a foreign pointer of the type that the FLI would generate for the parameter's type then the foreign object it points to will be the value of the parameter. The foreign pointer will be returned as a value, with the new contents as modified (or not) by the method.
Otherwise, the parameter is passed directly to the method and the value of the parameter at the end of the body will be returned as a value.