Marshaling Global Functions

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at Marshaling Global Functions.

These functions provide support for marshaling and converting marshaling data into interface pointers.

Important

The functions listed in the following table cannot be used in applications that execute in the Windows Runtime.

AtlFreeMarshalStream	Releases the marshal data and the IStream pointer.
AtlMarshalPtrInProc	Creates a new stream object and marshals the specified interface pointer.
AtlUnmarshalPtr	Converts a stream's marshaling data into an interface pointer.

AtlFreeMarshalStream

Releases the marshal data in the stream, then releases the stream pointer.

Important

This function cannot be used in applications that execute in the Windows Runtime.

HRESULT AtlFreeMarshalStream(IStream* pStream);

Parameters

pStream
[in] A pointer to the IStream interface on the stream used for marshaling.

Example

See the example for AtlMarshalPtrInProc.

AtlMarshalPtrInProc

Creates a new stream object, writes the CLSID of the proxy to the stream, and marshals the specified interface pointer by writing the data needed to initialize the proxy into the stream.

Important

This function cannot be used in applications that execute in the Windows Runtime.

HRESULT AtlMarshalPtrInProc(
    IUnknown* pUnk,
    const IID& iid,
    IStream** ppStream);

Parameters

pUnk
[in] A pointer to the interface to be marshaled.

iid
[in] The GUID of the interface being marshaled.

ppStream
[out] A pointer to the IStream interface on the new stream object used for marshaling.

Return Value

A standard HRESULT value.

Remarks

The MSHLFLAGS_TABLESTRONG flag is set so the pointer can be marshaled to multiple streams. The pointer can also be unmarshaled multiple times.

If marshaling fails, the stream pointer is released.

AtlMarshalPtrInProc can only be used on a pointer to an in-process object.

Example

//marshaling interface from one thread to another

//IStream ptr to hold serialized presentation of interface ptr
IStream* g_pStm;

//forward declaration
DWORD WINAPI ThreadProc(LPVOID lpParameter);

HRESULT WriteInterfacePtrToStream(IMyCircle *pCirc)
{
   //marshal the interface ptr to another thread
   //pCirc has to be pointer to actual object & not a proxy
   HRESULT hr = AtlMarshalPtrInProc(pCirc, IID_IMyCircle, &g_pStm);

   //m_dwThreadID is a DWORD holding thread ID of thread being created.
   CreateThread(NULL, 0, ThreadProc, NULL, 0, &m_dwThreadID);
   return hr;
}

DWORD WINAPI ThreadProc(LPVOID /*lpParameter*/)
{
   // CoInitializeEx is per thread, so initialize COM on this thread
   // (required by AtlUnmarshalPtr)
   HRESULT hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
   if (SUCCEEDED(hr))
   {
      IMyCircle* pCirc;

      //unmarshal IMyCircle ptr from the stream
      hr = AtlUnmarshalPtr(g_pStm, IID_IMyCircle, (IUnknown**)&pCirc);

      // use IMyCircle ptr to call its methods
      double center;
      pCirc->get_XCenter(&center);

      //release the stream if no other thread requires it 
      //to unmarshal the IMyCircle interface pointer
      hr = AtlFreeMarshalStream(g_pStm);

      CoUninitialize();
   }

   return hr;
}

AtlUnmarshalPtr

Converts the stream's marshaling data into an interface pointer that can be used by the client.

Important

This function cannot be used in applications that execute in the Windows Runtime.

HRESULT AtlUnmarshalPtr(
    IStream* pStream,
    const IID& iid,
    IUnknown** ppUnk);

Parameters

pStream
[in] A pointer to the stream being unmarshaled.

iid
[in] The GUID of the interface being unmarshaled.

ppUnk
[out] A pointer to the unmarshaled interface.

Return Value

A standard HRESULT value.

Example

See the example for AtlMarshalPtrInProc.

See Also

Functions