Navigation:  Programming Cookbook > Creating COM Components > Dolphins COM Framework >

Interfaces

Previous pageReturn to chapter overviewNext page

Implementing a COM server object (or coclass) requires that one provide a minimum of one interface class, and one implementation class.

Each COM interface that an object exposes requires one class. Custom interface classes are derived IUnknown, and dual interface classes from IDispatch. IUnknown has an abstract superclass, COMInterface, the main purpose of which is to separate out the the framework implementation of COM interfaces to avoid cluttering IUnknown. IDispatch is itself (like the interface it represents) derived from IUnknown.

Interface class consists of a set of external virtual function calls definitions following the normal Dolphin syntax (see External Interfacing), and (usually) a set of wrapper methods that make these easier to use within Smalltalk. Without the wrapper methods the raw COM functions are awkward to use, primarily because COM always returns values via output parameters, an idiom which is awkward even in C/C++. The reason for this is that the return value is, in lieu of proper exceptions, reserved for a success/failure return code value called an HRESULT. Negative HRESULTs indicate failure, positive (and zero) success. Dolphin’s VM and external call mechanism collaborate to automatically translate negative HRESULT codes into HRESULTError exceptions, so the responsibility of the wrapper methods is, where possible, to provide a method that fits more comfortably into Smalltalk’s message passing paradigm. Typically these wrapper methods (in fact the whole interface class) will be automatically generated by the Active-X Component Wizard.

The external method definitions of an interface class are sufficient to use that class for calling out to a COM server object implemented elsewhere, but in order to support call-in a table of function definitions is required. The table (actually an Array in vtable order) is built by the #defineFunctions method on the class side, and consists of a number of sub-instances of the COMFunctionAbstract class, mostly likely COMFunction instances. These function descriptor objects are responsible for mapping inbound virtual function calls to message sends to the actual server object, marshalling the parameters from the C stack into appropriate Smalltalk objects for the arguments.

The #defineFunctions method used to build the function table can also be generated by the Active-X Component Wizard. When the wizard is not used #defineFunctions can be written by hand, and the result used to generate the virtual function calls, but this is not recommended.