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
Returns pointers to supported interfaces.
Increments reference count.
Decrements reference count.

IMarshal Methods
Returns CLSID of unmarshaling code.
Returns size of buffer needed during marshaling.
Marshals an interface pointer.
Unmarshals an interface pointer.
Destroys a marshaled data packet.
Severs all connections.

See Also


Software for developers
Delphi Components
.Net Components
Software for Android Developers
More information resources
Unix Manual Pages
Delphi Examples