9 OLE FFI Facilities

9.3 C-to-Dylan name-mapping scheme

This section describes the scheme Functional Objects used to map the C names in the Microsoft OLE/COM API to names fitting Dylan style and coding conventions.

Class and type names are enclosed in angle brackets. For example, HRESULT becomes <HRESULT>. For Dylan classes representing C pointers, the Dylan = operator compares the pointer addresses, and == is not likely to be useful. (Comparison of structure contents, where applicable, is done by the same functions as in the C API.)
Names of constants are prefixed by a dollar sign ($). For example, NOERROR becomes $NOERROR.
Underscores are replaced by hyphens. For example, MAKE_HRESULT becomes MAKE-HRESULT and S_OK becomes $S-OK. (However, hyphens are not inserted between capitalized words.)
Functions whose only effect is to return a true-or-false value have a question mark (?) appended to their names. For example: SUCCEEDED?, FAILED?, and IsEqualIID?.
Where an interface function is documented under a name such as, for example, IClassFactory::CreateInstance, the corresponding Dylan generic function is called IClassFactory/CreateInstance. This means that function names generally need to be qualified by their interface names in Dylan, although they are not in C or C++. This is necessary because there are several names that are used in different interfaces with incompatible argument lists, so that the same generic function cannot be used. However, for convenience, the following alias names are defined:

  define constant QueryInterface = IUnknown/QueryInterface;

  define constant AddRef = IUnknown/AddRef;

  define constant Release = IUnknown/Release;

Where a C/C++ function takes a pointer argument as a place to store a result value (when that value is a pointer or integer, not when filling in fields in a structure), the corresponding Dylan function uses multiple return values to return such output parameters following the original function return value. For example, where C++ code says:

  status = obj->QueryInterface(IID_Ifoo, & result);

: the equivalent Dylan code is:

  let ( status :: <SCODE>, result :: <Interface> ) =
    QueryInterface(obj,$IID-Ifoo);

The multitude of integer data types in C code (int, long, unsigned, ULONG, DWORD, and so on) are all designated as <integer> (or some appropriate subrange thereof) in Dylan method argument types. However, in some cases, values that are too large to be represented as an <integer> are represented as a <machine-word> instead.

: The names <SCODE> and <HRESULT> are defined as Dylan data types because they are not used as integers even though they are implemented as such in C. (In Dylan, they are actually aliases for <machine-word>.)

The C type BOOL is mapped to <boolean> in Dylan. Use #t and #f instead of TRUE and FALSE.
Because slot names are not in a separate name space in Dylan, the names of C structure fields will have the suffix -value added to form the name of the Dylan accessor function. For example, the C statement:

  pt->x = x;

: becomes in Dylan:

  pt.x-value := x;

The class <Interface> is an abstract class that includes all OLE interfaces, regardless of whether they are implemented in C or Dylan. Thus this is the appropriate declared type for a variable holding an arbitrary interface, such as returned by QueryInterface or CreateInstance. Classes such as <LPUNKNOWN>, <LPOLECONTAINER>, <LPOLEOBJECT>, and so on represent specific interfaces which could be implemented in either C or Dylan; conceptually these are subclasses of <Interface>, but they are currently actually implemented as aliases of <Interface> instead of as distinct types. . The C-FFI library's function pointer-cast can be used to convert an <Interface> to one of the more specific types. The classes <IUnknown>, <IOleContainer>, <IOleObject>, and so on are subclasses used for interfaces implemented in Dylan. Thus, the class hierarchy looks (conceptually) like:

   <Interface>
       |
    <LPUNKNOWN>
     /       \
    /       <IUnknown>
<LPOLEOBJECT>  /     \
   /   \      /       \
  /   <IOleObject>    ...
 ...       |
    <my-OleObject>

: where <my-OleObject> represents a user-defined Dylan class that provides an implementation of the IOleObject interface. Classes <IUnknown> and <IOleObject> do not have any direct instances.

The function call null-pointer(<LP...>) is used to create a null pointer of a particular interface type, where C code would just use NULL. The constant $NULL-interface is provided as a null instance of type <Interface>, which is not otherwise directly instantiable. The function null? can be used to test whether an instance of <Interface> (or any other C pointer type) is null. It also returns #t if the argument is #f. It is not valid to use null-pointer on a Dylan implementation class (that is, any subclass of <IUnknown>).