CoMarshalInterface
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 CoUnmarshalInterface function to extract the
data and initialize the proxy. CoMarshalInterface can marshal only
interfaces derived from IUnknown.
STDAPI CoMarshalInterface(
|
IStream *pStm, |
//Pointer to the stream used for marshaling |
|
REFIID riid, |
//Reference to the identifier of the interface |
|
IUnknown *pUnk, |
//Pointer to the interface to be marshaled |
|
DWORD dwDestContext, |
//Destination context |
|
void *pvDestContext, |
//Reserved for future use |
|
DWORD mshlflags |
//Reason for marshaling |
|
); |
|
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 IUnknown interface.
pUnk
[in] Pointer
to the interface to be marshaled; can be NULL if the caller does not have a
pointer to the desired interface. This interface must be derived from the IUnknown interface.
dwDestContext
[in]
Destination context where the specified interface is to be unmarshaled. 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).
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 MSHLFLAGS enumeration.
Return Values
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 CoInitialize or OleInitialize function was not called on
the current thread before this function was called.
IStream errors
This function
can also return any of the stream-access error values returned by the IStream interface.
Remarks
The CoMarshalInterface
function marshals the interface referred to by riid on the object whose IUnknown
implementation is pointed to by pUnk. To do so, the CoMarshalInterface
function performs the following tasks:
1. Queries the object for a pointer to the IMarshal interface. If the object
does not implement IMarshal, meaning that it relies on COM to provide
marshaling support, CoMarshalInterface gets a pointer to COM s default
implementation of IMarshal.
2. Gets the CLSID of the object s proxy by
calling IMarshal::GetUnmarshalClass, using whichever IMarshal interface
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 CoMarshalInterface for you. If you are writing your own
proxies and stubs, your proxy code and stub code should each call CoMarshalInterface
to correctly marshal interface pointers. Calling IMarshal directly 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, 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 COM s default
marshaling implementation when passing the interface pointer, you can call CoMarshalInterface
on the object to do so.
See Also