5.9.1 COM Automation
The
ffi/com library builds on COM automation to provide a
safe use of COM objects that support the
IDispatch
interface.
The ffi/com library is based on the
MysterX library by Paul Steckler. MysterX is included with
Racket but deprecated, and it will be replaced in the next version
with a partial compability library that redirects to this one.
5.9.1.1 GUIDs, CLSIDs, IIDs, and PROGIDs
Returns
#t if
v is a structure representing a
GUID,
#f otherwise. The
clsid? and
iid? functions are the same as
guid?.
A GUID corresponds an a _GUID structure at the unsafe
layer.
Converts a string of the form
"{00000000-0000-0000-0000-0000000000}", where each
0 can
be a hexadecimal digit, to a
GUID. If
str does not
have te expected form, the
exn:fail exception is raised.
The string->clsid and string->iid functions are the
same as string->guid.
Converts a
GUID to its string form.
Determines whether
g1 and
g2 represent the same
GUID.
5.9.1.2 COM Objects
Returns #t if the argument is a COM object, #f
otherwise.
Returns an instance of the
COM class specified by
clsid-or-progid, which is either a
clsid or a
progid.
The optional where argument indicates a location for
running the instance, and may be 'local, 'remote,
or a string indicating a machine name. See Remote COM servers (DCOM) for
more information.
An object can be created this way for any COM class, but functions
such as com-invoke work only if the object supports the
IDispatch COM automation interface.
The resulting object is registered with the current custodian, which
retains a reference to the object until it is released with
com-release or the custodian is shut down.
Releases the given
COM object. The given
obj is
subsequently unusable, and the underlying COM object is destroyed
unless its reference count has been incremented (via COM methods or
unsafe operations).
Like
com-create-instance, but gets an existing
active object (always local) instead of creating a new one.
Returns the "clsid" of the COM class instantiated by
obj, or raises an error if the COM class is not known.
Sets the COM
clsid for
obj to
clsid. This
is useful when COM event-handling procedures can obtain only
ambiguous information about the object’s COM class.
Returns #t if the two COM objects are the same,
#f otherwise.
Returns #t if v represents reflective information
about a COM object’s type, #f otherwise.
Returns a representation of a COM object’s type that is independent of
the object itself.
Returns #t if t1 and t2 represent the same
type information, #f otherwise.
5.9.1.3 COM Methods
Returns a list of strings indicating the names of methods on
obj/type.
Returns a list indicating the type of the specified method in
obj/type. The list after the
'-> represents the
argument types, and the final value represents the result type. See
COM Types for more information.
Invokes
method-name on
obj with
vs as the
arguments. The special value
com-omit may be used for
optional arguments, which useful when values are supplied for
arguments after the omitted argument(s).
A constant for use with
com-invoke in place of an optional
argument.
5.9.1.4 COM Properties
Returns a list of strings indicating the names of readable
properties in obj/type.
Returns a type for
property-name like a result of
com-method, where the result type corresponds to the
property value type. See
COM Types for information on the
symbols.
Returns the value of the final property by following the indicated
path of propertys, where each intermediate property must be a
COM object.
Returns a list of strings indicating the names of writeable
properties in obj/type.
Returns a type for
property-name like a result of
com-method, where the sole argument type corresponds to the
property value type. See
COM Types for
information on the symbols.
Sets the value of the final property in obj to v
by following the propertys, where the value of each
intermediate property must be a COM object.
5.9.1.5 COM Events
Returns a list of strings indicating the names of events on
obj/type.
Returns a list indicating the type of the specified events in
obj/type. The list after the
'-> represents the
argument types. See
COM Types for more information.
Returns
#t if
v is a
COM event executor,
which queues event callbacks. A
COM event executor
com-ev-ex is a synchronizable event in the sense of
sync, and
(sync com-ev-ex) returns a thunk for a
ready callback.
Registers a callback for the event named by name in
obj. When the event fires, an invocation of proc to
event arguments (which depends on obj and name) is
queued in com-ev-ex. Synchronizing on com-ev-ex
produces a thunk that applies proc to the event arguments and
returns the result.
Only one callback can be registered for each obj and
name combination.
Registration of event callbacks relies on prior registration of the
COM class implemented by "myssink.dll" as distributed with
Racket. (The DLL is the same for all Racket versions.)
Removes any existing callback for name in obj.
5.9.1.6 Interface Pointers
Extracts an
IUnknown or
IDispatch pointer from
obj. The former succeeds for any
COM object that has
not been relased via
com-release. The latter succeeds
only when the
COM object supports
IDispatch, otherwise
exn:fail is raised.
Returns #t if v corresponds to an unsafe
IDispatch, #f otherwise.
5.9.1.7 Remote COM servers (DCOM)
The optional where argument to com-create-instance
can be 'remote. In that case, the server instance is run at
the location given by the Registry key
HKEY_CLASSES_ROOT\AppID\‹CLSID›\RemoteServerName
where ‹CLSID› is the CLSID of the application. This key may
be set using the dcomcnfg utility. From dcomcnfg, pick
the application to be run on the Applications tab, then
click on the Properties button. On the Location
tab, choose Run application on the following computer, and
enter the machine name.
To run a COM remote server, the registry on the client machine must
contain an entry at
HKEY_CLASSES_ROOT\CLSID\‹CLSID›
where ‹CLSID› is the CLSID for the server. The server
application itself need not be installed on the client machine.
There are a number of configuration issues relating to DCOM. See
http://www.distribucon.com/dcom95.html
for more information on how to setup client and server machines for DCOM.
5.9.1.8 COM Types
In the result of a function like com-method-type, symbols are
used to represent various atomic types:
'int — a 32-bit signed integer
'unsigned-int — a 32-bit unsigned integer
'short — a 16-bit signed integer
'unsigned-short — a 16-bit unsigned integer
'char — an 8-bit signed integer
'unsigned-char — an 8-bit unsigned integer
'long-long — a 64-bit signed integer
'unsigned-long-long — a 64-bit unsigned integer
'float — a 32-bit floating-point number
'double — a 64-bit floating-point number
'currency — an exact number that, when multiplied by 10,000,
is a 64-bit signed integer
'boolean — a boolean
'string — a string
'date — a date or date*
'com-object — a COM object as in com-object?
'iunknown — an IUnknown pointer as in com-iunknown?
'com-enumeration — a 32-bit signed integer
'any — any of the above
'void — no value
A type symbol wrapped in a list with 'box, such as
'(box int), is a call-by-reference argument. A box supplied
for the argument is updated with a new value when the method returns.
A type wrapped in a list with 'opt, such as '(opt (box int)), is an optional argument. The argument can be omitted or
replaced with com-omit.
5.9.1.9 Class Display Names
A coclass name corresponds to the display name of a COM
class; the display name is not uniquely mapped to a COM class, and
some COM classes have no display name.
Returns a list of
coclass strings for all COM classes in the
system registry that have the
"Control" subkey.
Converts a
coclass string to/from a
CLSID. This
conversion is implemented by an enumeration an
COM classes from
the system registry.