IMarshal::MarshalInterface method (objidl.h)

Article
08/19/2022

Marshals an interface pointer.

Syntax

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

Parameters

[in] pStm

A pointer to the stream to be used during marshaling.

[in] riid

A reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknown interface.

[in] pv

A pointer to the interface pointer to be marshaled. This parameter can be NULL if the caller does not have a pointer to the desired interface.

[in] dwDestContext

The destination context where the specified interface is to be unmarshaled. Possible values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

[in] pvDestContext

This parameter is reserved and must be 0.

[in] mshlflags

Indicates whether the data to be marshaled is to be transmitted back to the client process—the typical case—or written to a global table, where it can be retrieved by multiple clients. Possible values come from the MSHLFLAGS enumeration.

Return value

This method can return the standard return value E_FAIL, as well as the following values.

Return code	Description
S_OK	The interface pointer was marshaled successfully.
E_NOINTERFACE	The specified interface is not supported.
STG_E_MEDIUMFULL	The stream is full.

Remarks

This method is called indirectly, in a call to CoMarshalInterface, by whatever code in the server process is responsible for marshaling a pointer to an interface on an object. This marshaling code is usually a stub generated by COM for one of several interfaces that can marshal a pointer to an interface implemented on an entirely different object. Examples include the IClassFactory and IOleItemContainer interfaces. For purposes of discussion, the code responsible for marshaling a pointer is called the marshaling stub.

Notes to Callers

Typically, rather than calling MarshalInterface directly, your marshaling stub instead should call the CoMarshalInterface function, which contains a call to this method. The stub makes this call to command an object to write its marshaling data into a stream. The stub then either passes the marshaling data back to the client process or writes it to a global table, where it can be unmarshaled by multiple clients. The stub's call to CoMarshalInterface is normally preceded by a call to CoGetMarshalSizeMax to get the maximum size of the stream buffer into which the marshaling data will be written.

You do not explicitly call this method if you are implementing existing COM interfaces or defining your own interfaces using the Microsoft Interface Definition Language (MIDL). In either case, the MIDL-generated stub automatically makes the call.

If you are not using MIDL to define your own interface, your marshaling stub must call this method, either directly or indirectly. Your stub implementation should call MarshalInterface immediately after its previous call to IMarshal::GetMarshalSizeMax returns. Because the value returned by GetMarshalSizeMax is guaranteed to be valid only as long as the internal state of the object being marshaled does not change, a delay in calling MarshalInterface runs the risk that the object will require a larger stream buffer than originally indicated.

If the caller has a pointer to the interface to be marshaled, it should, as a matter of efficiency, use the pv parameter to pass that pointer. In this way, an implementation that may use such a pointer to determine the appropriate CLSID for the proxy does not have to call QueryInterface on itself. If a caller does not have a pointer to the interface to be marshaled, it can pass NULL.

Notes to Implementers

Your implementation of MarshalInterface must write to the stream whatever data is needed to initialize the proxy on the receiving side. Such data would include a reference to the interface to be marshaled, a MSHLFLAGS value specifying whether the data should be returned to the client process or written to a global table, and whatever is needed to connect to the object, such as a named pipe, handle to a window, or pointer to an RPC channel.

Your implementation should not assume that the stream is large enough to hold all the data. Rather, it should gracefully handle a STG_E_MEDIUMFULL error. Just before exiting, your implementation should position the seek pointer in the stream immediately after the last byte of data written.

If the pv parameter is NULL and your implementation needs an interface pointer, it can call QueryInterface on the current object to get it. The pv parameter exists merely to improve efficiency.

To ensure that your implementation of MarshalInterface continues to work properly as new destination contexts are supported in the future, delegate marshaling to the COM default implementation for all dwDestContext values that your implementation does not handle. To delegate marshaling to the COM default implementation, call the CoGetStandardMarshal helper function.

Using the MSHLFLAGS enumeration, callers can specify whether an interface pointer is to be marshaled back to a single client or written to a global table, where it can be unmarshaled by multiple clients. You must make sure that your object can handle calls from the multiple proxies that might be created from the same initialization data.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	objidl.h (include ObjIdl.h)