Applies to: desktop apps | Metro style apps
Writes into a stream the data required to initialize a proxy object in some client process.
Syntax
HRESULT CoMarshalInterface( __in LPSTREAM pStm, __in REFIID riid, __in LPUNKNOWN pUnk, __in DWORD dwDestContext, __in_opt LPVOID pvDestContext, __in DWORD mshlflags );
Parameters
- pStm [in]
-
A pointer to the stream to be used during marshaling. See IStream.
- riid [in]
-
A reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknown interface.
- pUnk [in]
-
A pointer to the interface to be marshaled. This interface must be derived from the IUnknown interface.
- dwDestContext [in]
-
The destination context where the specified interface is to be unmarshaled. The possible values come 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 computer (MSHCTX_DIFFERENTMACHINE).
- pvDestContext [in, optional]
-
This parameter is reserved and must be NULL.
- mshlflags [in]
-
The flags that specify 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. The possibles values come from the MSHLFLAGS enumeration.
Return value
This function can return the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, the stream-access error values returned by IStream, as well as the following values.
| Return code | Description |
|---|---|
|
The HRESULT was marshaled successfully. |
|
The CoInitialize or OleInitialize function was not called on the current thread before this function was called. |
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:
-
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.
-
Gets the CLSID of the object's proxy by calling IMarshal::GetUnmarshalClass, using whichever IMarshal interface pointer has been returned.
-
Writes the CLSID of the proxy to the stream to be used for marshaling.
-
Marshals the interface pointer by calling IMarshal::MarshalInterface.
The COM library in the client process calls the CoUnmarshalInterface function to extract the data and initialize the proxy. Before calling CoUnmarshalInterface, seek back to the original position in the stream.
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.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
Send comments about this topic to Microsoft
Build date: 3/7/2012
After CoMarshalInterface completes successfully, make sure you reset the stream so that when you try to unmarshal you don't get the error STG_E_READFAULT. You need to do this immediately after calling CoMarshalInterface in the process you're marshalling from as calling Seek in the destination process before unmarshalling may not work correctly.
Here's a complete example:
CComPtr<IStream> spStream;
hr = ::CreateStreamOnHGlobal(NULL, TRUE, &spStream.p);
ATLENSURE_RETURN_HR(hr == S_OK, hr);
hr = ::CoMarshalInterface(spStream, riid, spObjectToMarshal, MSHCTX_LOCAL, NULL, MSHLFLAGS_NORMAL);
ATLENSURE_RETURN_HR(hr == S_OK, hr);
LARGE_INTEGER zero;
zero.QuadPart = 0L;
hr = spStream->Seek(zero, STREAM_SEEK_SET, NULL);
ATLENSURE_RETURN_HR(hr == S_OK, hr);