Marshaling Data

For out-of-process and remote servers, you must consider how COM marshals data outside the current process. You can provide marshaling:

Automatically, using the IDispatch interface.
Automatically, by creating a type library with your server and marking the interface with the OLE Automation flag. COM knows how to marshal all the Automation-compatible types in the type library and can set up the proxies and stubs for you. Some type restrictions apply to enable automatic marshaling.
Manually by implementing all the methods of the IMarshal interface. This is called custom marshaling.

Note: The first method (using IDispatch) is only available on Automation servers. The second method is automatically available on all objects that are created by wizards and which use a type library.

Automation compatible types

Function result and parameter types of the methods declared in dual and dispatch interfaces and interfaces that you mark as OLE Automation must be Automation-compatible types. The following types are OLE Automation-compatible:

First, the predefined valid types such as Smallint, Integer, Single, Double, WideString. For a complete list, see Valid types.

Second, enumeration types defined in a type library. OLE Automation-compatible enumeration types are stored as 32-bit values and are treated as values of type Integer for purposes of parameter passing.

Third, interface types defined in a type library that are OLE Automation safe, that is, derived from IDispatch and containing only OLE Automation compatible types.

Fourth, dispinterface types defined in a type library.

Fifth, any custom record type defined within the type library.

Sixth, IFont, IStrings, and IPicture. Helper objects must be instantiated to map

an IFont to a TFont
an IStrings to a TStrings
an IPicture to a TPicture

The ActiveX control and ActiveForm wizards create these helper objects automatically when needed. To use the helper objects, call the global routines, GetOleFont, GetOleStrings, GetOlePicture, respectively.

Type restrictions for automatic marshaling

For an interface to support automatic marshaling (also called Automation marshaling or type library marshaling), the following restrictions apply. When you edit your object using the type library editor, the editor enforces these restrictions:

String data types must be transferred as wide strings (BSTR). PChar and AnsiString cannot be marshaled safely.
All members of a dual interface must pass an HRESULT as the function's return value. If the method is declared using the safecall calling convention, this condition is imposed automatically, with the declared return type converted to an output parameter.
Members of a dual interface that need to return other values should specify these parameters as var or out, indicating an output parameter that returns the value of the function.

Note: One way to bypass the Automation types restrictions is to implement a separate IDispatch interface and a custom interface. By doing so, you can use the full range of possible argument types. This means that COM clients have the option of using the custom interface, which Automation controllers can still access. In this case, though, you must implement the marshaling code manually.

Custom marshaling

Typically, you use automatic marshaling in out-of-process and remote servers because it is easier—COM does the work for you. However, you may decide to provide custom marshaling if you think you can improve marshaling performance. When implementing your own custom marshaling, you must support the IMarshal interface. For more information, on this approach, see the Microsoft documentation.