Understanding Custom Marshaling Part 1

where <main folder> is wherever you have copied the zip file to.

Inside BasicSample01, there are 3 additional folders : Interfaces, Implementations and Clients. Let us now examine the projects contained within these folders.

The BasicSample01Interfaces Solution

Inside the Interfaces folder, we have a Visual Studio .NET project folder named BasicSample01Interfaces in which the Visual Studio .NET solution project BasicSample01Interfaces.sln is found.

This BasicSample01Interfaces.sln project will not contain any useful implementation code. Its purpose is simply to allow us to automate (via ATL Wizards) the creation and maintenance of two COM interfaces named IImmutable and IImmutableObjectFactory.

Listed below is a fragment of code taken from BasicSample01Interfaces.idl showing the IImmutable and the IImmutableObjectFactory interfaces :

[ 
 object, 
 uuid(BF0DC81A-46FB-4300-88E5-2B8EEB2CEEA1), 
 dual, 
 nonextensible, 
 helpstring("IImmutable Interface"), 
 pointer_default(unique) 
] 
interface IImmutable : IDispatch  
{  
 [propget, id(1), helpstring("property LongValue")] 
          HRESULT LongValue([out, retval] LONG* pVal); 
}; 
 
[ 
 object, 
 uuid(CCAB57EA-A497-44C0-B0A4-E781B7F47AA9), 
 dual, 
 nonextensible, 
 helpstring("IImmutableObjectFactory Interface"), 
 pointer_default(unique) 
] 
interface IImmutableObjectFactory : IDispatch 
{ 
 [id(1), helpstring("method CreateObject")] 
          HRESULT CreateObject 
          ( 
            [in] LONG InitializationValue, 
            [out,retval] IImmutable** ppIImmutableObjectReceiver 
          ); 
}; 

Note that the IImmutable interface definition stipulates the basic attributes of this interface in terms of its GUID, methods, argument types, etc.

Customizable attributes like the apartment type, packaging format (in-proc DLL or EXE server) and whether standard or custom marshaling will be used, are the decision of the eventual implementation code.

An object which implements the IImmutable interface must possess a readonly long property. This readonly property must also never change once set internally.

The IImmutableObjectFactory interface describes an object which serves as a factory of IImmutable objects. An IImmutableObjectFactory object must implement the CreateObject() method which serves as an entry point for the creation and initialization of an IImmutable object. This method takes a long parameter which is used as the value to be set for the long property of the IImmutable object to be created and returned.

The BasicSample01Interfaces.sln solution will specifically help to maintain the BasicSample01Interfaces.idl file, which will be referenced by the BasicSample01InterfacesImpl.sln project (will be described in the next sub-section), and the BasicSample01Interfaces.h header file, which will be referenced by the various client codes included in the source codes zip file.

The BasicSample01InterfacesImpl Solution

Next, we examine the BasicSample01InterfacesImpl.sln project the folder of which can be found in the Implementations folder.

The BasicSample01InterfacesImpl.sln project contains concrete classes which implement the IImmutable and IImmutableObjectFactory interfaces. These are the CImmutableObjectFactoryImpl and the CImmutableImpl C++ classes respectively.

Let us now examine these classes in greater detail.

The CImmutableObjectFactoryImpl class

The CImmutableObjectFactoryImpl class is implemented using ATL. It is an STA class but this fact is not important as we will not be performing any custom marshaling for this interface. If CImmutableObjectFactoryImpl should be instantiated inside an STA thread, no marshaling will be immediately required in order that it be usable by the current apartment.However, if it is instantiated inside an MTA thread, then marshaling will be immediately required but we will be relying on standard marshaling for this.

Besides these immediate needs, any other cross apartment marshaling for CImmutableObjectFactoryImpl's IImmutableObjectFactory interface will also use standard marshaling.

Listed below is the implementation code for the only method of the IImmutableObjectFactory interfce :

STDMETHOD(CreateObject) 
( 
  long InitializationValue, 
  IImmutable ** ppIImmutableObjectReceiver 
) 
{ 
  CComObject<CImmutableImpl>* pCImmutableImpl = NULL; 
      
  CComObject<CImmutableImpl>::CreateInstance(&pCImmutableImpl); 
       
  if (pCImmutableImpl) 
  { 
    CImmutableImpl* pBase 
      = dynamic_cast<CImmutableImpl*>(pCImmutableImpl); 
       
    if (pBase) 
    { 
      pBase -> SetLongValue(InitializationValue); 
    } 
       
    pCImmutableImpl -> QueryInterface 
    ( 
      IID_IImmutable, 
      (void**)ppIImmutableObjectReceiver 
    ); 
  } 
      
  return S_OK; 
} 

The CreateObject() method simply creates an instance of CImmutableImpl and then sets its long property value by calling its non-COM public function SetLongValue(). The long value used here is taken from CreateObject()'s first parameter.

CreateObject() then returns a pointer to the new CImmutableImpl instance's IImmutable interface via QueryInterface().

The CImmutableImpl class

The CImmutableImpl class is also implemented using ATL. Like CImmutableObjectFactoryImpl, it is designated as an STA object. This means that if it is instantiated inside an STA thread, marshaling will not be immediately required. However, if it is instantiated inside an MTA thread, marshaling will be immediately required. This would complicate matters a little. We will be demonstrating something similar to this in a more advanced sample in a future article. The current basic sample client code will not be touching on this. The cross-apartment marshaling we will be demonstrating in our basic sample will be across two STA apartments.

CImmutableImpl supports the IImmutable interface by defining a long member data m_lLongValue. This long value is set via the non-COM public function named SetLongValue(). This method is only callable from code within the BasicSample01InterfacesImpl.dll server itself and only CImmutableObjectFactoryImpl uses it to initialize a CImmutableImpl object's long value.

The heart and soul of CImmutableImpl, however, is in its implementation of the IMarshal interface. CImmutableImpl shows its support for the IMarshal interface in its class definition :

class ATL_NO_VTABLE CImmutableImpl : 
 public CComObjectRootEx<CComSingleThreadModel>,
 public CComCoClass<CImmutableImpl, &CLSID_ImmutableImpl>,
        ...
 public IMarshal
{
   ...
   ...
   ...
}

The IMarshal interface requires implementors to supply six methods. We shall examine CImmutableImpl's implementations of these functions below.

GetUnmarshalClass()

HRESULT GetUnmarshalClass( 
  REFIID riid, 
  void * pv, 
  DWORD dwDestContext, 
  void * pvDestContext, 
  DWORD mshlflags, 
  CLSID * pCid 
); 

The GetUnmarshalClass() method is fully documented in MSDN. It is the first IMarshal method that COM will invoke after determining that an object will be performing its own custom marshaling (through the discovery of the object's IMarshal interface). COM calls this method to determine the CLSID of the marshaling proxy object. It is the proxy that will perform the unmarshaling of the original object in the importing client apartment.

In our basic sample, because the proxy is an exact copy of the object itself, i.e., the CImmutableImpl object is its own proxy. Hence the following code can be found in CImmutableImpl::GetUnmarshalClass():

STDMETHOD(GetUnmarshalClass) 
( 
  REFIID riid, 
  void * pv, 
  DWORD dwDestContext, 
  void * pvDestContext, 
  DWORD mshlFlags, 
  CLSID* pCid 
) 
{ 
  // The class that will perform the unmarshaling will be 

  // this class itslf. 

  *pCid = GetObjectCLSID(); 
 
  return S_OK; 
} 

We simply return the CLSID of the CImmutableImpl class itself. This tells COM that once CImmutableImpl has performed the necessary marshaling process and has acquired a marshal data packet stream (these are accomplished via the IMarshal::MarshalInterface() method), COM should then create, in the target client apartment, another instance of the CImmutableImpl class which will serve as the proxy to the original object.

The following diagram illustrates what happens when GetUnmarshalClass() is called :

GetMarshalSizeMax()

HRESULT GetMarshalSizeMax( 
  REFIID riid, 
  void * pv, 
  DWORD dwDestContext, 
  void * pvDestContext, 
  DWORD mshlflags, 
  ULONG * pSize 
); 

GetMarshalSizeMax() is the second IMarshal method that COM will invoke. The purpose of this method is to determine the size of the marshal data packet to be created for marshaling the IImmutable interface. This method works in pair with the MarshalInterface() method as we shall see later. Once COM has determined this size value, it will proceed to prepare the stream object (a container for bytes) which will be used to store the marshal data packet.

CImmutableImpl's implementation of GetMarshalSizeMax() is listed below :

STDMETHOD(GetMarshalSizeMax) 
( 
  REFIID riid,  
  void * pv, 
  DWORD dwDestContext, 
  void * pvDestContext, 
  DWORD mshlFlags, 
  ULONG* pSize 
) 
{ 
  HRESULT hr = S_OK; 
 
  *pSize = sizeof(CImmutableMarshaledObjectReferenceStruct); 
 
  return hr; 
}

Here we see that the size of the CImmutableMarshaledObjectReferenceStruct structue will be returned. This is because we will be storing a CImmutableMarshaledObjectReferenceStruct structure into the marshal data packet.

The CImmutableMarshaledObjectReferenceStruct structure is listed below :

typedef struct 
  CImmutableMarshaledObjectReferenceStructTag
{
  long lLongValue;
}
CImmutableMarshaledObjectReferenceStruct;

As mentioned earlier, to COM, the customized data contained inside the marshal data packet is essentially an opaque array of bytes that can contain anything as long as a proxy knows how to use it to establish communication with the original COM object or to re-create the object within the context of the client apartment. For our CImmutableImpl class, this customized array of bytes will contain the CImmutableMarshaledObjectReferenceStruct structue. As we shall see later on, this structure contains all the necessary information for our proxy to re-create the original object in the client apartment.

The following diagram illustrates what happens when GetMarshalSizeMax() is called :

MarshalInterface()

HRESULT MarshalInterface( 
  IStream * pStm, 
  REFIID riid, 
  void * pv, 
  DWORD dwDestContext, 
  void * pvDestContext, 
  DWORD mshlflags 
); 

The MarshalInterface() method is the next method to be called. This is a very important method as it is here that the marshal data packet will be created and end up being serialized and marshaled across to a target apartment. Whatever we place into the marshling data packet should contain information that will help the proxy to uniquely identify and establish connection with the original CImmutableImpl object (in order to invoke its properties and methods) or to re-create it in the context of the client apartment.

CImmutableImpl's MarshalInterface() method is listed below :

STDMETHOD(MarshalInterface)  
( 
  IStream* pStm, 
  REFIID riid, 
  void *pv, 
  DWORD dwDestContext, 
  void * pvDestContext,  
  DWORD mshlFlags 
) 
{       
  if (dwDestContext != MSHCTX_INPROC) 
  { 
    return E_FAIL; 
  } 
     
  CImmutableMarshaledObjectReferenceStruct 
    ImmutableMarshaledObjectReferenceStruct; 
     
  ImmutableMarshaledObjectReferenceStruct.lValue = m_lValue; 
     
  *pStm << ImmutableMarshaledObjectReferenceStruct; 
     
  return S_OK; 
} 

We stipulate that the marshaling context must be MSHCTX_INPROC (ie. the unmarshaling will be done in another apartment in the same process). The other marshaling contexts are not supported in our basic example.

We essentially create a CImmutableMarshaledObjectReferenceStruct structure and fill its only member data lValue with the current value in m_lValue. Once this is done, we will write the contents of our structure into the stream. We use a global stream support function (listed in marshalhelpers.h) to perform this.

The CImmutableMarshaledObjectReferenceStruct structure is used to store the current value of the m_lValue member data (which is returned when the IImmutable interface's LongValue property is requested by a client). This structure will be contained as raw bytes in the marshal data packet and will be passed to the IMarshal::UnmarshalInterface() method of the proxy which will reverse-transform these raw bytes into a CImmutableMarshaledObjectReferenceStruct structure. More on this later.

The following diagram illustrates what happens when MarshalInterface() is called :

UnmarshalInterface()

HRESULT UnmarshalInterface( 
  IStream * pStm, 
  REFIID riid, 
  void ** ppv 
); 

The UnmarshalInterface() method is to be implemented by a proxy. It is meant to be the congugal opposite of the MarshalInterface() method which is meant to be implemented by the original object. However, CImmutableImpl provides an implementation because it is its own proxy class. What happens before UnmarshalInterface() is invoked is that a new instance of CImmutableImpl (playing the role of a proxy) will be created inside the client apartment. Thereafter, this new instance's UnmarshalInterface() method will be called with an IStream pointer of the stream object which contains the marshal data packet created previously during the MarshalInterface() call.

What is expected from the UnmarshalInterface() method call is to return an interface pointer (whose IID is specified by the riid parameter) from the unmarshaled object (i.e. the proxy).

Let us examine CImmutableImpl's UnmarshalInterface() method :

STDMETHOD(UnmarshalInterface) 
( 
  IStream* pStm, 
  REFIID riid, 
  void ** ppv 
) 
{ 
  CImmutableMarshaledObjectReferenceStruct 
    ImmutableMarshaledObjectReferenceStruct; 
  
  *pStm >> 
    (CImmutableMarshaledObjectReferenceStruct&) 
      ImmutableMarshaledObjectReferenceStruct; 
 
  m_lValue = ImmutableMarshaledObjectReferenceStruct.lValue; 
  
  return QueryInterface(riid, ppv); 
} 

We create a new instance of the CImmutableMarshaledObjectReferenceStruct struct which is used to download all the contents of the input stream. Thereafter, we reconstruct CImmutableImpl by retrieving the lValue member of the structure and filling m_lValue with this value. This is exactly how the proxy becomes a "Marshal-By-Value" proxy. The original object is effectively re-created. And in our simple example, this completes the reconstruction process.

We then perform a QueryInterface() to retrieve the required interface pointer. The interface required is none other than that of IImmutable (i.e., IID_IImmtable).

The following diagram illustrates what happens when UnmarshalInterface() is called :

ReleaseMarshalData()

HRESULT ReleaseMarshalData( 
  IStream * pStm 
); 

This method is COM's way of indicating to an object (which has been marshaled) that a marshal object packet is being destroyed. The ocurrence of this is a very important event. However it is not significant in our basic example, as will be the case for most "Marshal-by-value" proxies. It is related to two concepts known as table marshaling and strong connections. In general only strong table-marshaled objects need to provide a non-trivial implementation of ReleaseMarshalData().This topic will be discussed again in a more advanced article in the future.

CImmutableImpl's version of ReleaseMarshalData() is listed below :

STDMETHOD (ReleaseMarshalData)(IStream *pStm) 
{ 
  return S_OK; 
} 

It is a trivial implementation indeed.

DisconnectObject()

HRESULT DisconnectObject( 
  DWORD dwReserved 
); 

This method applies only to objects which are housed within EXE COM servers. The typical situation in which this method is called on an object is when the EXE COM server is forcibly terminated while it still has at least one running object. In this situation, prior to shutting down, the EXE server must invoke the CoDisconnectObject() API on each of these running objects. For each object that implements IMarshal, CoDisconnectObject() will call the IMarshal::DisconnectObject() method so that each object that manages its own marshaling can take steps to notify its proxy that it is about to shut down.

After this is done, clients which hold proxies may continue to call the proxy's methods but the proxy must then return the HRESULT CO_E_OBJECTNOTCONNECTED.

This method is equally irrelevant to "Marshal-by-Value" proxies because a proxy is a clone of the original object and will not need to communicate with it. The above-described scenario do not apply for our basic example. Hence CImmutableImpl's version of DisconnectObjectI() is also trivial :

STDMETHOD (DisconnectObject)(DWORD dwReserved) 
{ 
  return S_OK; 
}  

The Client Solutions

I have prepared 3 separate client projects each of which illustrate a slightly different way to marshal and unmarshal our immutable object across apartments. These solutions are contained within the Clients folder. Let us examine these projects individually.

The VCConsoleClient01 Solution

The VCConsoleClient01.sln project provides a good basic example of demonstrating cross-apartment marshaling and unmarshaling with the lowest-level techniques available : i.e. via the CoMarshalInterface() and CoUnmarshalInterface() APIs and the creation of a stream object via CreateStreamOnHGlobal().

One of the highlights of the VCConsoleClient01 solution is our examination of the contents of the marshal data packet that will be created after we call the CoMarshalInterface() API.

VCConsoleClient01.sln is a console-based application. The following is a synopsis of this application :

1. A thread is started in which an instance of the IImmutableObjectFactory object is created and from which an instance of the IImmutable object is gotten.
2. The IImmutable object is then marshaled and a marshal data packet will be created for it.
3. The marshal data packet is then transported across to another apartment where it is examined and the IImmutable interface contained inside is imported.
4. After importing the IImmutable interface, we will use the proxy to call a method of the IImm<CODE>utable interface.

The source codes of the VCConsoleClient01 solution is simple enough for us to break it down into its constituent components and have them analyzed individually. These are summarized below :

The _tmain() function

The _tmain() function is the entry point of the application. It is listed below :

int _tmain(int argc, _TCHAR* argv[])
{
    ::CoInitialize(NULL);
    
    g_hInterfaceMarshaled = CreateEvent(NULL, TRUE, FALSE, NULL);
    
    Demonstrate_Cross_Apartment_Call_Via_Stream();
    
    if (g_hInterfaceMarshaled)
    {
      CloseHandle(g_hInterfaceMarshaled);
      g_hInterfaceMarshaled = NULL;
    }
 
    ::CoUninitialize();
    
  return
0;
}

Nothing sophisticated about the _tmain function. It essentially initializes the thread that it runs on to be an STA thread. It then creates an event handle g_hInterfaceMarshaled which will be signalled when the IImmutable object has been marshaled. _tmain than calls the Demonstrate_Cross_Apartment_Call_Via_Stream function. This function is where the real action starts.

The Demonstrate_Cross_Apartment_Call_Via_Stream() Function

The Demonstrate_Cross_Apartment_Call_Via_Stream() function is where the good stuff begins. This function works hand-in-hand with another named ThreadFunc_CustomMarshaledObject() to provide a complete demonstration of exporting and importing an interface pointer from one apartment to another.

Due to its length, we will not be printing a complete listing in this section. Instead we will provide a general synopsis of this function. Specific parts of this function will be examined closely in a later section when we discuss how it works together with ThreadFunc_CustomMarshaledObject().

Here below is a general synopsis :

1. It creates a thread headed by the entry point function ThreadFunc_CustomMarshaledObject().
2. ThreadFunc_CustomMarshaledObject() will create an IImmutable object (through a IImmutableObjectFactory object) and initialize its long value to some number. After creating the IImmutable object, it will create a marshal data packet for it and pass it (via an IStream interface pointer) to Demonstrate_Cross_Apartment_Call_Via_Stream().
3. After receiving the IStream interface pointer to the marshal data packet, Demonstrate_Cross_Apartment_Call_Via_Stream() will cast it to a MarshalDataPacket structure for examination purposes.
4. Next, the marshal data packet is unmarshaled and we will then obtain a proxy to the original IImmutable object. However, because the proxy is actually a "Marshal-By-Value" proxy, what we will obtain is actually a clone of the original IImmutable object.
5. We will use the proxy to obtain the long value contained inside. We will note that the long value is indeed the one that was used to initialize the original IImmutable object.

The ThreadFunc_CustomMarshaledObject() Function

As mentioned previously, ThreadFunc_CustomMarshaledObject() works hand-in-hand with Demonstrate_Cross_Apartment_Call_Via_Stream().

Here below is a general synopsis of this function :

1. ThreadFunc_CustomMarshaledObject() is the entry point function of a thread.
2. It is initialized to be an STA thread.
3. An instance of the IImmutableObjectFactory object is created and from this, an instance of a IImmutable object is obtained.
4. The IImmutable object is then marshaled. The resultant marshal data packet is then transported to the Demonstrate_Cross_Apartment_Call_Via_Stream() function.
5. ThreadFunc_CustomMarshaledObject() then enters a message loop which will not break until a WM_QUIT message is posted to this thread.
6. The fact that this thread remains alive (via the message pump) means that the IImutable object will also remain alive for perusal by other apartments.

How do the two functions work together ?

In this section, we examine how the above two functions work together to demonstrate marshaling/unmarshaling. We will also see the IMarshal methods of the IImmutable object in action while marshaling and unmarshaling take place. We will describe what goes on chronologically starting from the Demonstrate_Cross_Apartment_Call_Via_Stream() function.

1. Demonstrate_Cross_Apartment_Call_Via_Stream() starts by creating a new thread headed by the entry point function ThreadFunc_CustomMarshaledObject().
   
   
2. It also defines an uninitialized pointer to an IStream interface named lpStream:

   // lpStream is an uninitialized pointer to a stream.
   
   LPSTREAM lpStream = NULL;
   

3. We will pass the address of lpStream to the CreateThread() API as the parameter to the ThreadFunc_CustomMarshaledObject() entry point function :

     // We create a thread which is started by the function
   
     // ThreadFunc_CustomMarshaledObject(). We also pass the
   
     // uninitialized IStream pointer to this thread function
   
     // as a parameter.
   
     hThread = CreateThread
     (
       (LPSECURITY_ATTRIBUTES)NULL,
       (SIZE_T)0,
       (LPTHREAD_START_ROUTINE)ThreadFunc_CustomMarshaledObject,
       (LPVOID)(&lpStream),
       (DWORD)0,
       (LPDWORD)&dwThreadId
     );  
   

   This is done so that it will be initialized by ThreadFunc_CustomMarshaledObject() to point to the marshal data packet for the IImmutable object which will be created in that thread.
   

4. After creating the thread, Demonstrate_Cross_Apartment_Call_Via_Stream() will wait for the g_hInterfaceMarshaled event handle to be set :

     // We wait for the thread to initialize.
   
     ThreadMsgWaitForSingleObject(g_hInterfaceMarshaled, INFINITE);
    
     ResetEvent(g_hInterfaceMarshaled);
   

5. This event handle was first created inside _tmain(). It will be set inside ThreadFunc_CustomMarshaledObject() when the IImmutable object has been marshaled :

       // Signal the situation that the immutable object
   
       // has been marshaled by setting the g_hInterfaceMarshaled
   
       // event.
   
       if (g_hInterfaceMarshaled)
       {
         SetEvent(g_hInterfaceMarshaled);
       }
   

   When this event handle is set, it is a signal to the Demonstrate_Cross_Apartment_Call_Via_Stream() function that its lpStream now holds a marshal data packet and is ready for use.
   

6. On the ThreadFunc_CustomMarshaledObject() side, the pointer to lpStream is represented by the local variable named ppStreamReceiver. It will be initialized to the value of the LPVOID parameter passed from Demonstrate_Cross_Apartment_Call_Via_Stream() which is actually the address of the IStream pointer lpStream:

   DWORD WINAPI ThreadFunc_CustomMarshaledObject(LPVOID lpvParameter)
   {
     MSG  msg;
     long  lLong = 0;
     LPSTREAM* ppStreamReceiver = (LPSTREAM*)lpvParameter;
     ...
     ...
     ...
   

7. ThreadFunc_CustomMarshaledObject() will then proceed to create an IImmutableObjectFactory object and thereafter, to obtain an IImmutable object from it :

     // Create an instance of the COM object which has ProgID 
   
     // "BasicSample01InterfacesImpl.ImmutableObjectFactoryImpl" 
   
     // and manage it
   
     // via its IImmutableObjectFactory interface.
   
     // Now, because the resultant object (spIImmutableObjectFactory) 
   
     // is an STA object, and this thread is an STA thread, 
   
     // spIImmutableObjectFactory will live in the same STA 
   
     // as this thread.
   
     _CoCreateInstance
     (
       "BasicSample01InterfacesImpl.ImmutableObjectFactoryImpl", 
       spIImmutableObjectFactory
     );
       
     // Get the immutable object from spIImmutableObjectFactory.
   
     // Now because the immutable object is also an STA object, 
   
     // it will live in the same STA as this thread.
   
     spIImmutableObjectFactory -> CreateObject
     (
       101, 
       (IImmutable**)&spIImmutable
     );
   

   Note that IImmutable object's long property will be initialized to a value of 101.
   

8. ThreadFunc_CustomMarshaledObject() will then create a stream object using the CreateStreamOnHGlobal() API :

       ::CreateStreamOnHGlobal
       (
         0,
         TRUE,
         ppStreamReceiver
       );
   

   The CreateStreamOnHGlobal() API is used to create a Stream Object which will reside in global memory. We set the first parameter to zero to indicate that we want CreateStreamOnHGlobal() to internally allocate a new shared memory block of size zero. The second parameter is set to TRUE so that when the returned stream object is Release()'d, the global memory will also be freed.

   The newly allocated stream object will be returned as an IStream pointer. CreateStreamOnHGlobal() expects a pointer to a LPSTREAM in its third parameter. For this, we pass ppStreamReceiver. This way, lpStream (from Demonstrate_Cross_Apartment_Call_Via_Stream()) is set to store the resultant pointer to the IStream interface of the newly created stream object.
   

9. The CoMarshalInterface() API is then used to create a marshal data packet for the IImmutable object :

         ::CoMarshalInterface
         (
           *ppStreamReceiver,
           __uuidof(IImmutablePtr),
           (IUnknown*)pIUnknown,
           MSHCTX_INPROC,
           NULL,
           MSHLFLAGS_NORMAL
         );
   

   For the first parameter, CoMarshalInterface() expects a pointer to a stream object to be used during marshaling. For this, we pass the contents of ppStreamReceiver. This way, the lpStream (from Demonstrate_Cross_Apartment_Call_Via_Stream()) is used to store the marshal data packet of the IImmutable object. The use of the MSHCTX_INPROC as the destination context (parameter 4) indicates that the unmarshaling of the data in the stream will be done in another apartment of the same process.

   The use of the MSHLFLAGS_NORMAL flag (parameter 6) indicates that the marshal data packet can be unmarshaled just once, or not at all.

   During the course of running CoMarshalInterface(), COM will attempt to get the CLSID of the proxy for the IImmutable object and then to get the marshal data packet from it.

   The following sequence of function calls on the side of the IImmutable object will take place :

   CImmutableImpl::GetUnmarshalClass()
CImmutableImpl::GetMarshalSizeMax()
CImmutableImpl::MarshalInterface()

   The reader may want to put a breakpoint in these functions for observation purposes.

10. When CImmutableImpl::GetUnmarshalClass() is called, we will indicate to CoMarshalInterface the CLSID of the object that will take charge of unmarshaling the interface pointers of the IImmutable object. This will be the CLSID of the CImmutableImpl object itself. Note that the parameters to GetUnmarshalClass will reflect the parameter values of CoMarshalInterface.
    
    
11. When CImmutableImpl::GetMarshalSizeMax() is called, we will pass the size of the CImmutableMarshaledObjectReferenceStruct structure.
    
    
12. When CImmutableImpl::MarshalInterface() is called, notice that we create a CImmutableMarshaledObjectReferenceStruct structure and then serialize it into the stream object whose IStream interface is passed as first parameter.
    
    
13. After CoMarshalInterface() completes, we must reset the stream to the beginning. Otherwise a later call to the CoUnmarshalInterface() API using this same stream object will fail with error STG_E_READFAULT :

          // We will need to reset the stream to the beginning.
    
          // Otherwise a later call to the CoUnmarshalInterface() 
    
          // API will fail with error STG_E_READFAULT.
    
         (*ppStreamReceiver) -> Seek(li, STREAM_SEEK_SET, NULL);
    

14. Demonstrate_Cross_Apartment_Call_Via_Stream() will then pass lpStream to the ExamineStream() function for a closer look at what the marshal data packet contains. More on ExamineStream() later.
    
    
15. Demonstrate_Cross_Apartment_Call_Via_Stream() will then pass lpStream to the CoUnmarshalInterface() API to construct a proxy to the IImmutable interface from the stream :

        ::CoUnmarshalInterface
        (
          lpStream,
          __uuidof(IImmutablePtr),
          (void**)&spIImmutable
        );
    

16. Note that at this point in time, the Marshal Data Packet is contained inside the stream. All COM needs is a new proxy object to which it passes the Marshal Data Packet (in the UnmarshalInterface method call). When CoUnmarshalInterface is called with our marshal data packet stream, COM will create a proxy to the IImmutable object created inside the ThreadFunc_CustomMarshaledObject thread.
    
    
17. During the course of execution of the CoUnmarshalInterface API, COM will pass the marshal data packet stream to the proxy in order for it to be initialized. The following sequence of function calls will take place :

    CImmutableImpl() (constructor)
    CImmutableImpl::FinalConstruct() (part of proxy construction)
    CImmutableImpl::UnmarshalInterface() (the marshal data packet will be passed here).
    

    The reader is encouraged to place breakpoints inside these functions to see the sequence of CImmutableImpl function calls.
    

18. Notice that in CImmutableImpl::UnmarshalInterface(), a reverse of the activities of CImmutableImpl::MarshalInterface() is performed. A proxy which is effectively a clone of the original IImmutable object is constructed.
    
    
19. After the proxy to the IImmutable object has been created and initialized, Demonstrate_Cross_Apartment_Call_Via_Stream() will proceed to call its get_LongValue() method :

      // At this time, spIImmutable has been initialized to be a proxy
    
      // of the immutable object.
    
      if (spIImmutable)
      {   
        spIImmutable -> get_LongValue(&lLongValue);        
      }
    

    The value 101 will be returned, proving that the proxy is indeed a clone of the original object.
    

20. Thereafter Demonstrate_Cross_Apartment_Call_Via_Stream will terminate the ThreadFunc_CustomMarshaledObject thread by posting a WM_QUIT message to it :

    PostThreadMessage(dwThreadId, WM_QUIT, 0, 0);

21. When ThreadFunc_CustomMarshaledObject receives the WM_QUIT message, it will exit its message loop and head towards the end of the function. CoUninitialize is called and the IImmutableObjectFactory and IImmutable smart pointer objects will be destroyed, thereby Release()'ing them.

The ExamineStream() Function

The ExamineStream function uses standard IStream manipulation APIs to cast the data contained inside a stream into a MarshalDataPacket structure. This structure is listed below :

struct MarshalDataPacket
{
  char   Signature[4];
  char   chFlags;
  IID   iidMarshaledInterface;
  CLSID   clsidCustomProxy;
  unsigned long ul;
  unsigned long ulSize;
  unsigned char ucCustomMarshalDataBytes[1];
};

Notice that it is a complete representation of the marshal data packet illustrated in the "The Marshal Data Packet" section. The MarshalDataPacket struct is defined to help us cast the contents of a marshal data packet to a structure which will make its analysis much easier.

The ExamineStream function will allocate in memory a buffer which is the size of the stream object pointed to by the lpStream parameter. After that, its contents are copied into a MarshalDataPacket structure instance.

The diagram below shows a QuickWatch on the field values of this structure :

The format of the marshal data packet is revealed. We can see how the raw bytes of the customized part of the marshal data is used to contain the value of the lLongValue field (value 101) of the CImmutableMarshaledObjectReferenceStruct structure.

The Other Client Solutions

I have included two other client solutions which are contained inside the VCConsoleClient02 and VCConsoleClient03 folders. We do not have to go through their code as they are each sufficiently similar to VCConsoleClient01. My intention is to demonstrate other methods of marshaling and unmarshaling interfaces across apartments.

The following is a summary of their special features :

VCConsoleClient02

Instead of CoMarshalInterface() and CoUnmarshalInterface(), CoMarshalInterThreadInterfaceInStream() and CoGetInterfaceAndReleaseStream() are used. Please refer to MSDN for details on these two APIs.

These two APIs are actually warppers for the elaborate work that we did in VCConsoleClient01 of constructing a stream object and then using it to create a marshal data packet for marshaling and unmarshaling.

VCConsoleClient03

VCConsoleClient03 presents a radically different way of managing marshal data packets and proxies. It uses the Global Interface Table (GIT) to store the marshal data packet of an object. Whenever a proxy to the object is required, it is first created in the client apartment, then the marshal data packet from the GIT is retrieved and used to initialize the proxy.

In this example, the reader will see the IMarshal::ReleaseMarshalData() method in action. This method is COM's way of indicating to an object (which has been marshaled) that a marshaled object packet is being destroyed. A marshaled object reference can be considered an additional reference to an object. Hence, a call to ReleaseMarshalData should signal an object to perform reference count state management. This is especially true of objects which have been table-marshaled (i.e. their marshal data packets are stored in a table somewhere, e.g. the Global Interface Table) However it is not significant in our basic example, as will be the case for most "Marshal-by-value" proxies. This is because a "Marshal-by-value" proxy is independent of its original object.

Conclusion

In this first part of a multi-part dissertation on custom marshaling, I have attempted to provide an in-depth analysis of a proxy and a marshal data packet. In part two, we will go deeper by studying more advanced examples of custom marshaling. For the first time, we will touch on the role of stubs in custom marshaling.

Acknowledgements And References

Essential COM by Don Box. Published by Addison-Wesley