5.17.1 COM Automation

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 compatibility library that redirects to this one.

5.17.1.1 GUIDs, CLSIDs, IIDs, and ProgIDs

A GUID corresponds an a _GUID structure at the unsafe layer.

The string->clsid and string->iid functions are the same as string->guid.

The progid->clsid function accepts a versionless ProgID, in which case it produces the CLSID of the most recent available version. The clsid->progid function always produces a ProgID with its version.

5.17.1.2 COM Objects

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.

If obj has already been released, com-release has no effect.

If two references to a COM object are the same according to com-object-eq?, then they are also the same according to equal?. Two com-object-eq? references are not necessarily eq?, however.

5.17.1.3 COM Methods

The types of arguments are determined via com-method-type, if possible, and type-describe wrappers in the vs are simply replaced with the values that they wrap. If the types are not available from com-method-type, then types are inferred for each v with attention to descriptions in any type-describe wrappers in v.

Added in version 6.3.0.3 of package base.

5.17.1.4 COM Properties

Each property is either a property-name string or a list that starts with a property-name string and continues with arguments for a parameterized property.

The type of the property is determined via com-property-type, if possible, and type-describe wrappers in v are then replaced with the values that they wrap. If the type is not available from com-property-type, then a type is inferred for v with attention to the descriptions in any type-describe wrappers in v.

5.17.1.5 COM Events

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.)

5.17.1.6 COM Enumerations

A call (com-enumerate-to-list obj) is equivalent to (com-enumeration-to-list (com-get-property obj "_NewEnum")).

Added in version 6.2 of package base.

Added in version 6.2 of package base.

5.17.1.7 Interface Pointers

5.17.1.8 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.17.1.9 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-int — a 16-bit signed integer

• 'unsigned-short — a 16-bit unsigned integer

• 'signed-char — an 8-bit signed integer

• '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*; when converting to a date*, the timezone is reported as "UTC" and the year-day field is 0

• 'com-object — a COM object as in com-object?

• 'iunknown — like 'com-object, but also accepts an IUnknown pointer as in com-iunknown?

• 'com-enumeration — a 32-bit signed integer

• 'any — any of the above, or an array when not nested in an array type

• '... — treated like 'any, but when it appears at the end of the sequence of types for arguments, allows the preceding type 0 or more times

• '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.

A type wrapped in a list with 'array and a positive exact integer, such as '(array 7 int), represents a vector of values to be used as a COM array. A '? can be used in place of the length integer to support a vector of any length. Array types with non-'? lengths can be nested to specify a multidimensional array as represented by nested vectors.

A type wrapped in a list with 'variant, such as '(variant (array 7 int)), is the same as the wrapped type, but a 'variant wrapper within an 'array type prevents construction of another array dimension. For example, '(array 2 (array 3 int)) is a two-dimensional array of integers, but '(array 2 (variant (array 3 int))) is a one-dimensional array whose elements are one-dimensional arrays of integers.

When type information is not available, functions like com-invoke infer type descriptions from arguments. Inference chooses 'boolean for booleans; the first of 'int, 'unsigned-int, 'long-long, 'unsigned-long-long that fits for an exact integer; 'double for inexact real numbers; 'string for a string; 'com-object and 'iunknown for corresponding COM object references; and an 'array type for a vector, where the element type is inferred from vector values, resorting to 'any if any two elements have different inferred types.

A type-describe wrapper combines a base value with a type description. The description is used instead of an automatically inferred COM argument type when no type is available for from COM automation a method for com-invoke or a property for com-set-property!. A wrapper can be placed on an immediate value, or it can be on a value within a box or vector.

5.17.1.10 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.