5.18.1 COM Automation

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

► | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives
5.22 | Declaring Foreign Libraries Needed at Run Time

▼ | 5.18 | COM (Common Object Model)

5.18.1 | COM Automation
5.18.2 | COM Classes and Interfaces
5.18.3 | Active X Controls

► | 5.18.1 | COM Automation

5.18.1.1 | GUIDs, CLSIDs, IIDs, and Prog IDs
5.18.1.2 | COM Objects
5.18.1.3 | COM Methods
5.18.1.4 | COM Properties
5.18.1.5 | COM Events
5.18.1.6 | COM Enumerations
5.18.1.7 | Interface Pointers
5.18.1.8 | Remote COM servers (DCOM)
5.18.1.9 | COM Types
5.18.1.10 | Class Display Names

On this page:

5.18.1.1 GUIDs, CLSIDs, IIDs, and Prog IDs
guid?
clsid?
iid?
string->guid
string->clsid
string->iid
guid->string
guid=?
progid->clsid
clsid->progid
5.18.1.2 COM Objects
com-object?
com-create-instance
com-release
com-get-active-object
com-object-clsid
com-object-set-clsid!
com-object-eq?
com-type?
com-object-type
com-type=?
5.18.1.3 COM Methods
com-methods
com-method-type
com-invoke
com-omit
com-omit?
5.18.1.4 COM Properties
com-get-properties
com-get-property-type
com-get-property
com-get-property*
com-set-properties
com-set-property-type
com-set-property!
5.18.1.5 COM Events
com-events
com-event-type
com-event-executor?
com-make-event-executor
com-register-event-callback
com-unregister-event-callback
5.18.1.6 COM Enumerations
com-enumerate-to-list
com-enumeration-to-list
5.18.1.7 Interface Pointers
com-object-get-iunknown
com-object-get-idispatch
com-iunknown?
com-idispatch?
5.18.1.8 Remote COM servers (DCOM)
5.18.1.9 COM Types
type-description?
type-described?
type-describe
type-described-value
type-described-description
5.18.1.10 Class Display Names
com-all-coclasses
com-all-controls
coclass->clsid
clsid->coclass

Racket
top contents ← prev up next →

#### 5.18.1 COM Automation🔗ℹ

(require ffi/com) | package: base

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

##### 5.18.1.1 GUIDs, CLSIDs, IIDs, and ProgIDs🔗ℹ

> procedure (guid? v) → boolean?
> v : any/c
> procedure (clsid? v) → boolean?
> v : any/c
> procedure (iid? v) → boolean?
> v : any/c

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.

> procedure (string->guid str) → guid?
> str : string?
> procedure (string->clsid str) → clsid?
> str : string?
> procedure (string->iid str) → iid?
> str : string?

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.

> procedure (guid->string g) → string?
> g : guid?

Converts a GUID to its string form.

> procedure (guid=? g1 g2) → boolean?
> g1 : guid?
> g2 : guid?

Determines whether g1 and g2 represent the same GUID.

> procedure (progid->clsid progid) → clsid?
> progid : string?
> procedure (clsid->progid clsid) → (or/c string? #f)
> clsid : clsid?

Converts a ProgID to a CLSID or vice versa. Not evey COM class has a ProgID, so the result of clsid->progid can be #f.

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.18.1.2 COM Objects🔗ℹ

> procedure (com-object? obj) → boolean?
> obj : com-object?

Returns #t if the argument represents a COM object, #f otherwise.

> procedure (com-create-instance clsid-or-progid [where]) → com-object?
> clsid-or-progid : (or/c clsid? string?)
> where : (or/c 'local 'remote string?) = 'local

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.

> procedure (com-release obj) → void?
> obj : com-object?

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

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

> procedure (com-get-active-object clsid-or-progid) → com-object?
> clsid-or-progid : (or/c clsid? string?)

Like com-create-instance, but gets an existing active object (always local) instead of creating a new one.

> procedure (com-object-clsid obj) → clsid?
> obj : com-object?

Returns the "CLSID" of the COM class instantiated by obj, or raises an error if the COM class is not known.

> procedure (com-object-set-clsid! obj clsid) → void?
> obj : com-object?
> clsid : clsid?

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.

> procedure (com-object-eq? obj1 obj2) → boolean?
> obj1 : com-object?
> obj2 : com-object?

Returns #t if obj1 and obj2 refer to the same COM object, #f otherwise.

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.

> procedure (com-type? v) → boolean?
> v : any/c

Returns #t if v represents reflective information about a COM object’s type, #f otherwise.

> procedure (com-object-type obj) → com-type?
> obj : com-object?

Returns a representation of a COM object’s type that is independent of the object itself.

> procedure (com-type=? t1 t2) → boolean?
> t1 : com-type?
> t2 : com-type?

Returns #t if t1 and t2 represent the same type information, #f otherwise.

##### 5.18.1.3 COM Methods🔗ℹ

> procedure (com-methods obj/type) → (listof string?)
> obj/type : (or/c com-object? com-type?)

Returns a list of strings indicating the names of methods on obj/type.

> procedure (com-method-type obj/type method-name)
> | → |  |
> (list/c '-> (listof type-description?)
> type-description?)
> obj/type : (or/c com-object? com-type?)
> method-name : string?

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.

> procedure (com-invoke obj method-name v ...) → any/c
> obj : com-object?
> method-name : string?
> v : any/c

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

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.

> value com-omit : any/c

A constant for use with com-invoke in place of an optional argument.

> procedure (com-omit? v) → boolean?
> v : any/c

Returns #t if v is com-omit, #f otherwise.

Added in version 6.3.0.3 of package base.

##### 5.18.1.4 COM Properties🔗ℹ

> procedure (com-get-properties obj/type) → (listof string?)
> obj/type : (or/c com-object? com-type?)

Returns a list of strings indicating the names of readable properties in obj/type.

> > procedure
> > (com-get-property-type |  | obj/type |
> > |  | property-name) |
> → (list/c '-> '() type-description?)
> obj/type : (or/c com-object? com-type?)
> property-name : string?

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.

> procedure (com-get-property obj property ...+) → any/c
> obj : com-object?
> | property |  | : |  |
> (or/c string?
> (cons/c string? list?))

Returns the value of the final property by following the indicated path of propertys, where each intermediate property must be a COM object.

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.

> procedure (com-get-property* obj property v ...) → any/c
> obj : com-object?
> property : string?
> v : any/c

Returns the value of a parameterized property, which behaves like a method and accepts the vs as arguments (like com-invoke). When no vs are provided, com-get-property* is the same as com-get-property.

> procedure (com-set-properties obj/type) → (listof string?)
> obj/type : (or/c com-object? com-type?)

Returns a list of strings indicating the names of writeable properties in obj/type.

> > procedure
> > (com-set-property-type |  | obj/type |
> > |  | property-name) |
> → (list/c '-> (list/c type-description?) 'void)
> obj/type : (or/c com-object? com-type?)
> property-name : string?

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.

> procedure (com-set-property! obj property ...+ v) → void?
> obj : com-object?
> | property |  | : |  |
> (or/c string?
> (cons/c string? list?))
> v : any/c

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. A property can be a list instead of a string to represent a parameterized property and its arguments.

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.18.1.5 COM Events🔗ℹ

> procedure (com-events obj/type) → (listof string?)
> obj/type : (or/c com-object? com-type?)

Returns a list of strings indicating the names of events on obj/type.

> procedure (com-event-type obj/type event-name)
> → (list/c '-> (listof type-description?) 'void)
> obj/type : (or/c com-object? com-type?)
> event-name : string?

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.

> procedure (com-event-executor? v) → boolean?
> v : any/c

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.

> procedure (com-make-event-executor) → com-event-executor?

Creates a fresh COM event executor for use with com-register-event-callback.

> > procedure
> > (com-register-event-callback |  | obj |  |  |  |
> > |  | name |  |  |  |
> > |  | proc |  |  |  |
> > |  | com-ev-ex) |  | → |  | void?
> obj : com-object?
> name : string?
> proc : procedure?
> com-ev-ex : com-event-executor?

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

> procedure (com-unregister-event-callback obj name) → void?
> obj : com-object?
> name : string?

Removes any existing callback for name in obj.

##### 5.18.1.6 COM Enumerations🔗ℹ

> procedure (com-enumerate-to-list obj) → list?
> obj : com-object?

Produces the elements that obj would generate as the driver of a for-each loop in Visual Basic or PowerShell.

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.

> procedure (com-enumeration-to-list obj) → list?
> obj : com-object?

Given a COM object that implements IEnumVARIANT, extracts the enumerated values into a list.

Added in version 6.2 of package base.

##### 5.18.1.7 Interface Pointers🔗ℹ

> procedure (com-object-get-iunknown obj) → com-iunkown?
> obj : com-object?
> procedure (com-object-get-idispatch obj) → com-idispatch?
> obj : com-object?

Extracts an IUnknown or IDispatch pointer from obj. The former succeeds for any COM object that has not been released via com-release. The latter succeeds only when the COM object supports IDispatch, otherwise exn:fail is raised.

> procedure (com-iunknown? v) → boolean?
> v : any/c

Returns #t if v corresponds to an unsafe _IUnknown-pointer, #f otherwise. Every COM interface extends IUnknown, so com-iunknown? returns #t for every interface pointers.

> procedure (com-idispatch? v) → boolean?
> v : any/c

Returns #t if v corresponds to an unsafe IDispatch, #f otherwise.

##### 5.18.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.18.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.

> procedure (type-description? v) → boolean?
> v : any/c

Return #t if v is a COM argument or result type description as above, #f otherwise.

> procedure (type-described? v) → boolean?
> v : any/c
> procedure (type-describe v desc) → type-described?
> v : any/c
> desc : type-description?
> procedure (type-described-value td) → any/c
> td : type-described?
> procedure (type-described-description td) → type-description?
> td : type-described?

The type-described? predicate recognizes wrappers produced with type-describe, and type-described-value and type-described-description extract the value and description parts of a type-describe value.

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.18.1.10 Class Display Names🔗ℹ

(require ffi/com-registry) | package: base

The ffi/com-registry library provides a mapping from coclass names to CLSIDs for compatibility with the older MysterX interface.

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.

> procedure (com-all-coclasses) → (listof string?)

Returns a list of coclass strings for all COM classes registered on a system.

> procedure (com-all-controls) → (listof string?)

Returns a list of coclass strings for all COM classes in the system registry that have the "Control" subkey.

> procedure (coclass->clsid coclass) → clsid?
> coclass : string?
> procedure (clsid->coclass clsid) → string?
> clsid : clsid?

Converts a coclass string to/from a CLSID. This conversion is implemented by an enumeration an COM classes from the system registry.
top contents ← prev up next →