CoMarshalInterface - OLE Programmer's Reference (ole.hlp)

CoMarshalInterface

Marshals an interface pointer into the specified stream. Marshalling consists of writing the appropriate data into the stream so the CoUnmarshalInterface function can use that data to initialize a proxy object in another process. CoMarshalInterface can marshal only interfaces derived from IUnknown.

STDAPI CoMarshalInterface(

IStream *pStm,	//Stream used for marshalling
REFIID riid,	//Identifies interface being marshalled
IUnknown *pUnk,	//Interface pointer being marshalled
DWORD dwDestContext,	//Specifies destination process
void *pvDestContext,	//Reserved for future use
DWORD mshlflags	//Specifies reason for marshalling
);

Parameters
pStm

Points to the stream to be used during marshalling.

riid

Specifies the IID of the interface pointer being marshaled. This interface must be derived from the IUnknown interface.

pUnk

Points to the interface pointer to be marshalled.

dwDestContext

Specifies the destination context, which is the process in which the unmarshalling will be done. The legal values for dwDestContext are taken from the enumeration MSHCTX.

pvDestContext

Indicates reserved for future use; must be set to zero by the caller.

mshlflags

Specifies why marshalling is taking place. The legal values for mshlflags are taken from the MSHLFLAGS enumeration.

Return Values
S_OK

Indicates the interface pointer was marshalled successfully.

CO_E_NOTINITIALIZED

Indicates the CoInitialize or OleInitialize function was not called on the current thread before this function was called.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

Indicates one or more arguments are invalid.

E_UNEXPECTED

Indicates an unexpected error occurred.

E_FAIL

Indicates an unspecified error.

IStream errors

See the IStream interface for information on possible stream access errors.

Comments
The main steps that CoMarshalInterface performs are the following:

The function checks whether custom marshaling is supported by calling the QueryInterface function on pUnk and asking for an IMarshal interface pointer. If the object does not support custom marshalling, the function gets an IMarshal interface pointer to the system's standard marshalling implementation.
Using whichever IMarshal interface pointer it has acquired, the function calls IMarshal::GetUnmarshalClass to get the CLSID of the unmarshaller (the proxy to be created). Then it writes the CLSID to the stream.
The function calls IMarshal::MarshalInterface to marshal the interface pointer.

You typically do not need to call this function. OLE calls it from within interface proxies or stubs that marshal an interface pointer.

The only situation in which you might need to call this function is if you are performing custom marshalling (that is, writing your own implementation of IMarshal). Your implementation of IMarshal::MarshalInterface writes to a stream the data needed to initialize a custom proxy in the destination context. If your custom proxy will need access to a private object, you can include an interface pointer to that object as part of the data you write to the stream. In such situations, if you want to use standard marshalling when passing the interface pointer, you can call CoMarshalInterface to do so; this is an example of using standard marshaling within your implementation of custom marshaling.

See Also
CoUnmarshalInterface, IMarshal::MarshalInterface

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (sock2.hlp)
Unix Manual Pages

greatis just4fun network