5.17.2 COM Classes and Interfaces

5.17.2.1 Describing COM Interfaces

The order of the method-ids must match the specification of the COM interface, not including methods inherited from _super-id. Each method type produced by ctype-expr that is not _fpointer must be a function type whose first argument is the “self” pointer, usually constructed with _mfun or _hmfun.

The define-com-interface form binds _id, id ?, _id -pointer, _id _ vt (for the virtual-method table), _id _ vt-pointer, and method-id for each method whose ctype-expr is not _fpointer. (In other words, use _fpointer as a placeholder for methods of the interface that you do not need to call.) An instance of the interface will have type _id -pointer. Each defined method-id is bound to a function-like macro that expects a _id -pointer as its first argument and the method arguments as the remaining arguments.

A maybe-alloc-spec describes allocation and finalization information for a method along the lines of ffi/unsafe/alloc. If the maybe-alloc-spec is #:release-with-function function-id, then function-id is used to deallocate the result produced by the method, unless the result is explicitly deallocated before it becomes unreachable; for example, #:release-with-function Release is suitable for a method that returns a COM interface reference that must be eventually released. The #:release-with-method method-id form is similar, except that the deallocator is a method on the same object as the allocating method (i.e., one of the other method-ids or an inherited method). A #:releases annotation indicates that a method is a deallocator (so that a value should not be automatically deallocated if it is explicitly deallocated using the method).

See COM Interface Example for an example using define-com-interface.

5.17.2.2 Obtaining COM Interface References

Specific IIDs and intf-pointer-types go together. For example, IID_IUnknown goes with _IUnknown-pointer.

For a non-#f result, Release function is the automatic deallocator for the resulting pointer. The pointer is register with a deallocator after the cast to intf-pointer-type, which is why QueryInterface accepts the intf-pointer-type argument (since a cast generates a fresh reference).

If manage? is true, the resulting object is registered with the current custodian and a finalizer to call com-release when the custodian is shut down or when the object becomes inaccessible.

5.17.2.3 COM FFI Helpers

The _hfun form handles the _HRESULT value of the foreign call as follows:

• If the result is zero or if #:allow is specified and allow?-expr produces #t, then output-expr (as in a maybe-wrapper for _fun) determines the result.

• If the result is RPC_E_CALL_REJECTED or RPC_E_SERVERCALL_RETRYLATER, the call is automatically retried up to (current-hfun-retry-count) times with a delay of (current-hfun-retry-delay) seconds between each attempt.

• Otherwise, an error is raised using windows-error and using id as the name of the failed function.

Changed in version 6.2 of package base: Added #:allow and automatic retries.

Added in version 6.2 of package base.

Added in version 6.2 of package base.

When receiving a string value, cast it to _string/utf-16 to extract a copy of the string, and then free the original pointer with SysFreeString.

5.17.2.4 COM Interface Example

Here’s an example using the Standard Component Categories Manager to enumerate installed COM classes that are in the different system-defined categories. The example illustrates instantiating a COM class by CLSID, describing COM interfaces with define-com-interface, and using allocation specifications to ensure that resources are reclaimed even if an error is encountered or the program is interrupted.

#lang racket/base

(require ffi/unsafe

ffi/unsafe/com)

(provide show-all-classes)

; The function that uses COM interfaces defined further below:

(define (show-all-classes)

(define ccm

(com-create-instance CLSID_StdComponentCategoriesMgr))

(define icat (QueryInterface (com-object-get-iunknown ccm)

IID_ICatInformation

_ICatInformation-pointer))

(define eci (EnumCategories icat LOCALE_SYSTEM_DEFAULT))

(for ([catinfo (in-producer (lambda () (Next/ci eci)) #f)])

(printf "~a:\n"

(cast (array-ptr (CATEGORYINFO-szDescription catinfo))

_pointer

_string/utf-16))

(define eg

(EnumClassesOfCategories icat (CATEGORYINFO-catid catinfo)))

(for ([guid (in-producer (lambda () (Next/g eg)) #f)])

(printf " ~a\n" (or (clsid->progid guid)

(guid->string guid))))

(Release eg))

(Release eci)

(Release icat))

; The class to instantiate:

(define CLSID_StdComponentCategoriesMgr

(string->clsid "{0002E005-0000-0000-C000-000000000046}"))

; Some types and variants to match the specification:

(define _ULONG _ulong)

(define _CATID _GUID)

(define _REFCATID _GUID-pointer)

(define-cstruct _CATEGORYINFO ([catid _CATID]

[lcid _LCID]

[szDescription (_array _short 128)]))

; —— IEnumGUID ——-

(define IID_IEnumGUID

(string->iid "{0002E000-0000-0000-C000-000000000046}"))

(define-com-interface (_IEnumGUID _IUnknown)

([Next/g (_mfun (_ULONG = 1) ; simplifed to just one

(guid : (_ptr o _GUID))

(got : (_ptr o _ULONG))

-> (r : _HRESULT)

-> (cond

[(zero? r) guid]

[(= r 1) #f]

[else (windows-error "Next/g failed" r)]))]

[Skip _fpointer]

[Reset _fpointer]

[Clone _fpointer]))

; —— IEnumCATEGORYINFO ——-

(define IID_IEnumCATEGORYINFO

(string->iid "{0002E011-0000-0000-C000-000000000046}"))

(define-com-interface (_IEnumCATEGORYINFO _IUnknown)

([Next/ci (_mfun (_ULONG = 1) ; simplifed to just one

(catinfo : (_ptr o _CATEGORYINFO))

(got : (_ptr o _ULONG))

-> (r : _HRESULT)

-> (cond

[(zero? r) catinfo]

[(= r 1) #f]

[else (windows-error "Next/ci failed" r)]))]

[Skip _fpointer]

[Reset _fpointer]

[Clone _fpointer]))

; —— ICatInformation ——-

(define IID_ICatInformation

(string->iid "{0002E013-0000-0000-C000-000000000046}"))

(define-com-interface (_ICatInformation _IUnknown)

([EnumCategories (_hmfun _LCID

(p : (_ptr o _IEnumCATEGORYINFO-pointer))

-> EnumCategories p)]

[GetCategoryDesc (_hmfun _REFCATID _LCID

(p : (_ptr o _pointer))

-> GetCategoryDesc

(begin0

(cast p _pointer _string/utf-16)

(SysFreeString p)))]

[EnumClassesOfCategories (_hmfun (_ULONG = 1) ; simplifed

_REFCATID

(_ULONG = 0) ; simplifed

(_pointer = #f)

(p : (_ptr o

_IEnumGUID-pointer))

-> EnumClassesOfCategories p)

#:release-with-function Release]

[IsClassOfCategories _fpointer]

[EnumImplCategoriesOfClass _fpointer]

[EnumReqCategoriesOfClass _fpointer]))