IMarshal

The IMarshal interface allows an object to perform custom marshaling of interface pointers.

"Marshaling" is the process of packaging function parameters into data packets in order to send them to a different process or machine. "Unmarshaling" is the process of recovering those parameters when they are received. When a remote function call passes an interface pointer as a function parameter, that pointer is marshaled in such a way that it becomes possible for a client in one process to use that interface pointer to call methods on an object in another process.

OLE marshals an interface pointer by creating a proxy object in the client's process. A client holds an interface pointer to the proxy object and calls methods using that pointer; the proxy marshals the method parameters and sends them to the original process, thus forwarding the method call to the original object. The IMarshal interface allows an object to control what kind of proxies are created.

When to Implement
You almost never need to implement this interface. OLE provides a default implementation of IMarshal that uses OLE-generated proxy objects; this is suitable for almost all situations. You implement the IMarshal interface only if you want to perform custom marshaling; this allows you to write your own proxy objects.

OLE uses your implementation of IMarshal in the following manner: When it's necessary to create a remote interface pointer to your object (that is, when a pointer to your object is passed as a parameter in a remote function call), OLE queries your object for the IMarshal interface. If your object implements it, OLE uses your IMarshal implementation to create the proxy object. If your object does not implement IMarshal, OLE uses its standard implementation.

Some situations in which you might want to perform custom marshaling are as follows:

The objects you are writing keep their state in shared memory. In this case, both the original process and the client process uses proxies that refer to the shared memory. This type of custom marshaling is possible only if the client process is on the same machine as the original process. The compound file implementations of IStorage and IStream are examples of this type of custom marshaling.
The objects you are writing are immutable, that is, their state does not change after creation. Instead of forwarding method calls to the original objects, you can simply create copies of those objects in the client process. This technique avoids the cost of context switches (switching from one process to another). Monikers are an example of immutable objects; if you are implementing your own moniker class, you should perform custom marshaling.

Note that these situations do not require you to create a separate class of proxy objects; the same objects are used by both the original process and the client process. In other situations, you may need to write a separate class of proxy objects (with its own CLSID) that forward calls to the original objects, in addition to implementing IMarshal on the original objects.

When to Use
You typically do not need to call this interface. OLE is the primary user of this interface.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.

IMarshal Methods	Description
GetUnmarshalClass	Returns CLSID of unmarshaling code.
GetMarshalSizeMax	Returns size of buffer needed during marshaling.
MarshalInterface	Marshals an interface pointer.
UnmarshalInterface	Unmarshals an interface pointer.
ReleaseMarshalData	Destroys a marshaled data packet.
DisconnectObject	Severs all connections.