Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function writes into a stream the data required to initialize a proxy object in some client process. The COM library in the client process calls the CoUnmarshalInterfacefunction to extract the data and initialize the proxy. CoMarshalInterfacecan marshal only interfaces derived from IUnknown.

Syntax

STDAPI CoMarshalInterface(
  IStream* 
pStm,
  REFIID 
riid,
  IUnknown* 
pUnk,
  DWORD 
dwDestContext,
  void* 
pvDestContext,
  DWORD 
mshlflags
);

Parameters

pStm

[in] Pointer to the stream to be used during marshaling.

riid

[in] Reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknowninterface.

pUnk

[in] Pointer to the interface to be marshaled. This interface must be derived from the IUnknowninterface.

dwDestContext

[in] Destination context where the specified interface is to be unmarshaled. Values for dwDestContextcome from the enumeration MSHCTX.

Currently, unmarshaling can occur in another apartment of the current process (MSHCTX_INPROC), in another process on the same computer as the current process (MSHCTX_LOCAL), or in a process on a different machine (MSHCTX_DIFFERENTMACHINE).

pvDestContext

[in] Reserved for future use; must be NULL.

mshlflags

[in] Flag specifying whether the data to be marshaled is to be transmitted back to the client process — the normal case — or written to a global table, where it can be retrieved by multiple clients. Values come from the MSHLFLAGSenumeration.

Return Value

This function supports the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The interface pointer was marshaled successfully.

CO_E_NOTINITIALIZED

The CoInitializefunction was not called on the current thread before this function was called.

IStreamerrors

This function can also return any of the stream-access error values returned by the IStreaminterface.

Remarks

The CoMarshalInterfacefunction marshals the interface referred to by riid on the object whose IUnknownimplementation is pointed to by pUnk. To do so, the CoMarshalInterfacefunction performs the following tasks:

  1. Queries the object for a pointer to the IMarshalinterface. If the object does not implement IMarshal, meaning that it relies on COM to provide marshaling support, CoMarshalInterfacegets a pointer to COM's default implementation of IMarshal.

  2. Gets the CLSID of the object's proxy by calling IMarshal::GetUnmarshalClass, using whichever IMarshalinterface pointer has been returned.

  3. Writes the CLSID of the proxy to the stream to be used for marshaling.

  4. Marshals the interface pointer by calling IMarshal::MarshalInterface.

If you are implementing existing COM interfaces or defining your own interfaces using the Microsoft Interface Definition Language (MIDL), the MIDL-generated proxies and stubs call CoMarshalInterfacefor you.

If you are writing your own proxies and stubs, your proxy code and stub code should each call CoMarshalInterfaceto correctly marshal interface pointers. Calling IMarshaldirectly from your proxy and stub code is not recommended.

If you are writing your own implementation of IMarshal, and your proxy needs access to a private object, your application can include an interface pointer to that object as part of the data written to the stream. To use COM's default marshaling implementation when passing the interface pointer, your application can call CoMarshalInterfaceon the object.

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

Requirements

Header objbase.h
Library ole32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

COM Functions