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.

System_CAPS_ICON_important.jpg Important

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

AtlFreeMarshalStreamReleases the marshal data and the IStream pointer.
AtlMarshalPtrInProcCreates a new stream object and marshals the specified interface pointer.
AtlUnmarshalPtrConverts a stream's marshaling data into an interface pointer.

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

System_CAPS_ICON_important.jpg 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.

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.

System_CAPS_ICON_important.jpg 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;
}

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

System_CAPS_ICON_important.jpg 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.

Functions

Show: