set-i-dispatch-event-handler Function

Summary

Sets an event handler for an i-dispatch interface.

Package

com

Signature

set-i-dispatch-event-handler (interface event-handler &key all coclass event-object source-names) => sinks

Arguments

Values

Description

The function set-i-dispatch-event-handler sets an event handler for the i-dispatch interface interface.

event-handler is a function with the following signature:

event-handler event-obj method-name method-type args

event-obj is the value of event-object if this is non-nil. If event-object is nil, event-obj is the value of interface.

method-name is the method-name that has been called, which is the same as the "event" name in Visual Basic terminology.

method-type is the type of the method. For a normal "event" it is :method. method-type can also be :put or :get if the underlying "source" interface has "propput" or "propget" methods or properties.

args is an array containing the arguments to the method ("event"). This varies according to the method. For out or in-out arguments, it is possible to return a value by setting the corresponding value in the array.

all, coclass and source-names tell set-i-dispatch-event-handler which "source" interface or interfaces to use. In most cases, the default is correct.

If all is false, then only the "default" "source" is used. If all is true, then set-i-dispatch-event-handler uses all the source interfaces that the coclass defines.

coclass tells set-i-dispatch-event-handler which coclass to use, which is the same as the object in Visual Basic terminology.

If coclass is nil, it uses the first coclass in the type library that has the type of interface as a default interface, or if there is no such coclass, the first coclass that has this interface. In most of the cases this is the desired coclass.

If coclass is non-nil, it specifies which coclass to use. It can be a ProgID (for example "Word.Application") or a coclass name or a coclass GUID. If the i-dispatch interface was created with create-instance, then the argument to create-instance is the correct coclass to use.

If source-names is non-nil, then it is a list of "source" interface names to use, and all and coclass are ignored. If source-names is nil, then set-i-dispatch-event-handler calls get-i-dispatch-source-names to calculate the "source" interface names.

sinks is a list of objects representing the connections that set-i-dispatch-event-handler made. When the events are no longer needed, they can be released by disconnect-standard-sink.

Notes

1. set-i-dispatch-event-handler can be called more than once on the same i-dispatch, and this generates new connections each time. Therefore, if it is called more than once such that it uses the same source names, events will arrive more than once.
2. If you need to call set-i-dispatch-event-handler repeatedly, then it is most efficient to call get-i-dispatch-source-names once and pass the result source-names to set-i-dispatch-event-handler.
3. There is a useful function create-instance-with-events which combines create-instance and set-i-dispatch-event-handler.

See also

disconnect-standard-sink
create-instance-with-events
get-i-dispatch-source-names