The method supports the standard return value E_FAIL, as well as the following:

S_OK

The interface pointer was marshaled successfully.

E_NOINTERFACE

The specified interface is not supported.

STG_E_MEDIUMFULL

The stream is full.

This method is called indirectly, in a call to CoMarshalInterface, by whatever code in the server process may be 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. An example is the IClassFactoryinterface. For this discussion, the code responsible for marshaling a pointer is called the marshaling stub.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Typically, rather than calling IMarshal::MarshalInterfacedirectly, your marshaling stub instead should call the CoMarshalInterfacefunction, 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 CoMarshalInterfaceis typically 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 doing the following:

• Implementing existing COM interfaces
  
  
• Defining your own interfaces using the Microsoft Interface Definition Language (MIDL)
  
  

In both cases, the MIDL-generated stub 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 MarshalInterfaceimmediately after its previous call to IMarshal::GetMarshalSizeMaxreturns.

Because the value returned by GetMarshalSizeMaxis guaranteed to be valid only so long as the internal state of the object being marshaled does not change, a delay in calling MarshalInterfaceruns 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 QueryInterfaceon itself.

If a caller does not have a pointer to the interface to be marshaled, it can pass NULL.

Your implementation of IMarshal::MarshalInterfacemust write to the stream whatever data is needed to initialize the proxy on the receiving side. Such data would include the following:

• A reference to the interface to be marshaled
  
  
• A MSHLFLAGSvalue specifying whether the data should be returned to the client process or written to a global table
  
  
• Whatever is needed to connect to the object, such as a 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 pvparameter is NULL and your implementation needs an interface pointer, it can call IUnknown::QueryInterfaceon the current object to get it. The pvparameter exists merely to improve efficiency.

To ensure that your implementation of MarshalInterfacecontinues to work properly as new destination contexts are supported in the future, delegate marshaling to COM's default implementation for all dwDestContextvalues that your implementation does not handle.

To delegate marshaling to COM's default implementation, call the CoGetStandardMarshalhelper function.

Using the MSHLFLAGSenumeration, 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. Be sure your object can handle calls from the multiple proxies that might be created from the same initialization data.