define-com-method

define-com-method Macro

Summary

The macro define-com-method is used to define a COM method for a particular implementation class.

Package

com

Signature

define-com-method method-spec (class-spec {arg-spec}*) {form}*

method-spec ::= method-name | (interface-name method-name)

class-spec ::= (this class-name &key interface)

arg-spec ::= (parameter-name [direction [pass-style]])

Arguments

`method-spec`⇩	Specifies the method to be defined.
`class-spec`	Specifies the implementation class and variables bound to the object within `form`s.
`arg-spec`	Describes one of the method's arguments.
`form`⇩	Forms which implement the method. The value of the final form is returned as the result of the method.
`method-name`⇩	A symbol naming the method to define.
`interface-name`⇩	A symbol.
`this`⇩	A symbol which will be bound to the COM object whose method is being invoked.
`class-name`⇩	A symbol naming the COM implementation class for which this method is defined.
`interface`⇩	A optional symbol which will be bound to the COM interface pointer whose method is being invoked. Usually this is not needed unless the interface pointer is being passed to some other function in the implementation.
`parameter-name`⇩	A symbol which will be bound to that argument's value while `form`s are evaluated.
`direction`⇩	Specifies the direction of the argument, either `:in`, `:out` or `:in-out` If specified, it must match the definition of the interface. The default is taken from the definition of the interface.
`pass-style`⇩	Specifies how the argument will be converted to a Lisp value. It can be either `:lisp` or `:foreign`, the default is `:lisp`.

Description

The macro define-com-method defines a COM method that implements the method method-name for the COM implementation class class-name. The extended method-spec syntax containing interface-name is required if class-name implements more than one interface with a method called method-name (analogous to the C++ syntax InterfaceName::MethodName).

When the COM method is called, each form is evaluated in a lexical environment containing the following bindings.

The symbol this is bound to the instance of the COM implementation class on which the method is being invoked. The symbol this is also defined as a local macro (as if by with-com-object), which allows the body to invoke other methods on the instance.

If present, the symbol interface is bound to the interface pointer on which the method is being invoked.

Each foreign argument is converted to a Lisp argument as specified by its direction and pass-style and the corresponding parameter-name is bound to the converted value. See 1.9.6 Data conversion in define-com-method for details.

The value of the final form should be an hresult, which is returned from the COM method.

If an error is to be returned from an Automation method, the function set-error-info can be used to provide more details to the caller.

Examples

(define-com-method (i-robot rotate) 
    ((this i-robot-impl)
     (axis :in)
     (angle-delta :in))
  (let ((joint (find-joint axis)))
    (rotate-joint joint))
  S_OK)