Chapter 7. Persistence in ATL

A Review of COM Persistence

Objects that have a persistent state should implement at least one persistence interfaceand, preferably multiple interfacesto provide the container with the most flexible choice of how it wants to save the object’s state. Persistent state refers to data (typically properties and instance variables) that an object needs to have preserved before a container destroys the object. The container provides the saved state to the object after it re-creates the object so that the object can reinitialize itself to its previous state.

COM itself doesn’t require an object to support persistence, nor does COM use such support if it’s present in an object. COM simply documents a protocol by which clients can use any persistence support that an object provides. Often we refer to this persistence model as client-managed persistence because, in this model, the client determines where to save the persistent data (the medium) and when the save occurs.

COM defines some interfaces that model a persistence medium and, for some media, an implementation of the interfaces. Such interfaces typically use the naming convention IMedium, where the medium is Stream, Storage, PropertyBag, and so on. The medium interface has methods such as Read and Write that an object uses when loading and saving its state.

COM also documents interfaces that an object implements when it wants to support persistence into various media. Such interfaces typically use the naming convention IPersistMedium. The persistence interfaces have methods such as Load and Save that the client calls to request the object to restore or save its state. The client provides the appropriate medium interface to the object as an argument to the Load or Save requests. Figure 7.1 illustrates this model.

Figure 7.1. The client-managed persistence model

All IPersistMedium interfaces derive from the IPersist interface, which looks like this:

interface IPersist : IUnknown
{ HRESULT GetClassID([out] CLSID* pclsid); }

A client uses the GetClassID method when it wants to save the state of an object. Typically, the client queries for IPersistMedium, calls the GetClassID method to obtain the CLSID for the object the client wants to save, and then writes the CLSID to the persistence medium. The client then requests the object to save its state into the medium. Restoring the object is the inverse operation: The client reads the CLSID from the medium, creates an instance of the class, queries for the IPersistMedium interface on that object, and requests the object to load its state from the medium.

A client might ask an object to save its state in two basic forms: a self-describing set of named properties or an opaque binary stream of bytes.

When an object provides its state as a self-describing set of named properties, it provides each property as a name-type-value tuple to its client. The client then stores the properties in the form most convenient to the client, such as text on HTML pages. The benefit of self-describing data, such as <param> tags and XML, is that one entity can write it and another can read it without tight coupling between the two.

It is more efficient for an object to provide its state as a binary stream of bytes because the object doesn’t need to provide a property name or translate eachproperty into the name-type-value tuple. In addition, the client doesn’t need to translate the property to and from text. However, opaque streams contain machine dependencies, such as byte order and floating point/character set representations, unless specifically addressed by the object writing the stream.

ATL provides support for both forms of persistence. Before we explore ATL’s persistence implementation, let’s look at how you might implement COM persistence directly.

IPropertyBag and IPersistPropertyBag

ActiveX control containers that implement a “save as text” mechanism typically use IPropertyBag and IPersistPropertyBag. A container implements IPropertyBag, and a control implements IPersistPropertyBag to indicate that it can persist its state as a self-describing set of named properties:

interface IPropertyBag : public IUnknown {
  HRESULT Read([in] LPCOLESTR pszPropName,
    [in, out] VARIANT* pVar, [in] IErrorLog* pErrorLog);

  HRESULT Write([in] LPCOLESTR pszPropName, [in] VARIANT* pVar);
};

interface IPersistPropertyBag : public IPersist {
  HRESULT InitNew ();
  HRESULT Load([in] IPropertyBag* pPropBag,
    [in] IErrorLog* pErrorLog);
  HRESULT Save([in] IPropertyBag* pPropBag,
    [in] BOOL fClearDirty,
    [in] BOOL fSaveAllProperties);
};

When a client (container) wants to have exact control over how individually named properties of an object are saved, it attempts to use an object’s IPersistPropertyBag interface as the persistence mechanism. The client supplies a property bag to the object in the form of an IPropertyBag interface.

When the object wants to read a property in IPersistPropertyBag::Load, it calls IPropertyBag::Read. When the object saves properties in IPersistPropertyBag::Save, it calls IPropertyBag::Write. Each property is described with a name in pszPropName whose value is exchanged in a VARIANT. For read operations, the property bag provides the named property from the bag in the form specified by the input VARIANT, unless the type is VT_EMPTY; in that case, the property bag provides the property in any form that is convenient to the bag.

The information that the object provides for each property (name-type-value) during a save operation allows a client to save the property values as text, for instance. This is the primary reason a client might choose to support IPersistPropertyBag. The client records errors that occur during reading into the supplied error log.

IPropertyBag2 and IPersistPropertyBag2

The IPropertyBag interface doesn’t give an object much information about the properties contained in the bag. Therefore, the newer interface IPropertyBag2 gives an object much greater access to information about the properties in a bag. Objects that support persistence using IPropertyBag2 naturally implement the IPersistPropertyBag2 interface.

interface IPropertyBag2 : public IUnknown {
  HRESULT Read([in] ULONG cProperties, [in] PROPBAG2* pPropBag,
    [in] IErrorLog*  pErrLog, [out] VARIANT* pvarValue,
    [out] HRESULT*   phrError);
  HRESULT Write([in] ULONG cProperties, [in] PROPBAG2* pPropBag,
    [in] VARIANT*    pvarValue);
  HRESULT CountProperties ([out] ULONG* pcProperties);
  HRESULT GetPropertyInfo([in] ULONG iProperty,
    [in] ULONG cProperties,
    [out] PROPBAG2* pPropBag, [out] ULONG* pcProperties);
  HRESULT LoadObject([in] LPCOLESTR pstrName, [in] DWORD dwHint,
    [in] IUnknown* pUnkObject, [in] IErrorLog* pErrLog);
};

interface IPersistPropertyBag2 : public IPersist {
  HRESULT InitNew ();
  HRESULT Load ([in] IPropertyBag2* pPropBag,
    [in] IErrorLog* pErrLog);
  HRESULT Save ([in] IPropertyBag2* pPropBag,
    [in] BOOL fClearDirty,
    [in] BOOL fSaveAllProperties);
  HRESULT IsDirty();
};

IPropertyBag2 is an enhancement of the IPropertyBag interface. IPropertyBag2 allows the object to obtain the number of properties in the bag and the type information for each property through the CountProperties and GetPropertyInfo methods. A property bag that implements IPropertyBag2 must also support IPropertyBag so that objects that support only IPropertyBag can access their properties.Likewise, an object that supports IPersistPropertyBag2 must also support IPersistPropertyBag so that it can communicate with property bags that support only IPropertyBag.

When the object wants to read a property in IPersistPropertyBag2::Load, it calls IPropertyBag2::Read. When the object saves properties in IPersistPropertyBag2::Save, it calls IPropertyBag2::Write. The client records errors that occur during Read with the supplied IErrorLog interface.

Implementing IPersistPropertyBag

Clients ask an object to initialize itself only once. When the client has no initial values to give the object, the client calls the object’s IPersistPropertyBag::InitNew method. In this case, the object should initialize itself to default values. When the client has initial values to give the object, it loads the properties into a property bag and calls the object’s IPersistPropertyBag::Load method. When the client wants to save the state of an object, it creates a property bag and calls the object’s IPersistPropertyBag::Save method.

This is pretty straightforward to implement in an object. For example, the Demagogue object has three properties: its name, speech, and volume. Here’s an example of an implementation to save and restore the following three properties from a property bag:

class ATL_NO_VTABLE CDemagogue
    : public IPersistPropertyBag, ... {
    BEGIN_COM_MAP(CDemagogue)
      ...
      COM_INTERFACE_ENTRY(IPersistPropertyBag)
      COM_INTERFACE_ENTRY2(IPersist, IPersistPropertyBag)
    END_COM_MAP()
    ...
    CComBSTR m_name;
    long     m_volume;
    CComBSTR m_speech;

    STDMETHODIMP Load(IPropertyBag *pBag, IErrorLog *pLog) {
      // Initialize the VARIANT to VT_BSTR
      CComVariant v ((BSTR) NULL);
      HRESULT hr = pBag->Read(OLESTR("Name"), &v, pLog);
      if (FAILED(hr)) return hr;
      m_name = v.bstrVal;

      // Initialize the VARIANT to VT_I4
      v = 0L;
      hr = pBag->Read(OLESTR("Volume"), &v, pLog);
      if (FAILED(hr)) return hr;
      m_volume = v.lVal;

      // Initialize the VARIANT to VT_BSTR
      v = (BSTR) NULL;
      hr = pBag->Read(OLESTR("Speech"), &v, pLog);
      if (FAILED (hr)) return hr;
      m_speech = v.bstrVal;

      return S_OK;
    }

    STDMETHODIMP Save(IPropertyBag *pBag,
      BOOL fClearDirty, BOOL /* fSaveAllProperties */) {
      CComVariant v = m_name;
      HRESULT hr = pBag->Write(OLESTR("Name"), &v);
      if (FAILED(hr)) return hr;

      v = m_volume;
      hr = pBag->Write(OLESTR("Volume"), &v);
      if (FAILED(hr)) return hr;

      v = m_speech;
      hr = pBag->Write(OLESTR("Speech"), &v);
      if (FAILED(hr)) return hr;

      if (fClearDirty) m_fDirty = FALSE;
      return hr;
    }
};

The IStream, IpersistStreamInit, and IPersistStream Interfaces

COM objects that want to save their state efficiently as a binary stream of bytes typically implement IPersistStream or IPersistStreamInit. An ActiveX control that has persistent state must, at a minimum, implement either IPersistStream or IPersistStreamInit. The two interfaces are mutually exclusive and generally shouldn’t be implemented together. A control implements IPersistStreamInit when it wants to know when it is newly created, as opposed to when it has been created and reinitialized from its existing persistent state. The IPersistStream interface does not provide a means to inform the control that it is newly created. The existence of either interface indicates that the control can save and load its persistent state into a stream – that is, an implementation of IStream.

The IStream interface closely models the Win32 file API, and you can easily implement the interface on any byte-oriented media. COM provides two implementations of IStream, one that maps to an OLE Structured Storage file and another that maps to a memory buffer.

interface ISequentialStream : IUnknown {
    HRESULT Read([out] void *pv, [in] ULONG cb,
        [out] ULONG *pcbRead);

    HRESULT Write( [in] void const *pv, [in] ULONG cb,
        [out] ULONG *pcbWritten);

}

interface IStream : ISequentialStream {
  HRESULT Seek([in] LARGE_INTEGER dlibMove,
               [in] DWORD dwOrigin,
               [out] ULARGE_INTEGER *plibNewPosition);
  //...
}

interface IPersistStreamInit : public IPersist {
        HRESULT IsDirty();
        HRESULT Load([in] LPSTREAM pStm);
        HRESULT Save([in] LPSTREAM pStm, [in] BOOL fClearDirty);
        HRESULT GetSizeMax([out] ULARGE_INTEGER*pCbSize);
        HRESULT InitNew();
};

interface IPersistStream : public IPersist {
        HRESULT IsDirty();
        HRESULT Load([in] LPSTREAM pStm);
        HRESULT Save([in] LPSTREAM pStm, [in] BOOL fClearDirty);
        HRESULT GetSizeMax([out] ULARGE_INTEGER*pCbSize);
};

When a client wants an object to save its state as an opaque stream of bytes, it typically attempts to use the object’s IPersistStreamInit interface as the persistence mechanism. The client supplies the stream into which the object saves in the form of an IStream interface.

When the client calls IPersistStreamInit::Load, the object reads its properties from the stream by calling IStream::Read. When the client calls IPersistStreamInit::Save, the object writes its properties by calling IStream::Write. Note that unless the object goes to the extra effort of handling the situation, the stream contains values in an architecture-specific byte order.

Most recent clients prefer to use an object’s IPersistStreamInit interface; if it’s not present, they fall back and try to use IPersistStream. However, older client code might attempt to use only an object’s IPersistStream implementation. To be compatible with both types of clients, your object must implement IPersistStream. However, other containers ask for only IPersistStreamInit, so to be compatible with them, you need to implement that interface.

However, you’re not supposed to implement both interfaces because then it’s unclear to the container whether the object needs to be informed when it’s newly created. Pragmatically, the best solution to this dilemma is to support both interfaces when your object doesn’t care to be notified when it’s newly created, even though this violates the specification for controls.

Although IPersistStreamInit doesn’t derive from IPersistStream (it can’t because of the mutual exclusion aspect of the interfaces), they have identical v-tables for all methods except the last: the InitNew method. Because of COM’s binary compatibility, when your object doesn’t need an InitNew call, your object can hand out an IPersistStreamInit interface when asked for an IPersistStream interface. So with a single implementation of IPersistStreamInit and an extra COM interface map entry, your object becomes compatible with a larger number of clients.

class ATL_NO_VTABLE CDemagogue : public IPersistStreamInit, ... {
...
BEGIN_COM_MAP(CDemagogue)
  ...
  COM_INTERFACE_ENTRY(IPersistStreamInit)
  COM_INTERFACE_ENTRY_IID(IID_IPersistStream, IPersistStreamInit)
  COM_INTERFACE_ENTRY2(IPersist, IPersistStreamInit)
END_COM_MAP()
...
};

Implementing IPersistStreamInit

Clients ask an object to initialize itself only once. When the client has no initial values to give the object, the client calls the object’s IPersistSteamInit::InitNew method. In this case, the object should initialize itself to default values. When the client has initial values to give the object, the client opens the stream and calls the object’s IPersistStreamInit::Load method. When the client wants to save the state of an object, it creates a stream and calls the object’s IPersistStreamInit::Save method.

As in the property bag implementation, this is quite straightforward to implement in an object. Here’s an example of an implementation for the Demagogue object to save and restore its three properties to and from a stream:

class CDemagogue : public IPersistStreamInit, ... {
    CComBSTR m_name;
    long     m_volume;
    CComBSTR m_speech;
    BOOL     m_fDirty;

    STDMETHODIMP IsDirty() { return m_fDirty ? s_OK : S_FALSE; }

    STDMETHODIMP Load(IStream* pStream) {
        HRESULT hr = m_name.ReadFromStream(pStream);
        if (FAILED (hr)) return hr;

        ULONG cb;
        hr = pStream->Read (&m_volume, sizeof (m_volume), &cb);
        if (FAILED (hr)) return hr;
        hr = m_speech.ReadFromStream(pStream);
        if (FAILED (hr)) return hr;
        m_fDirty = FALSE ;
        return S_OK;
    }

    STDMETHODIMP Save (IStream* pStream) {
        HRESULT hr = m_name.WriteToStream (pStream);
        if (FAILED(hr)) return hr;

        ULONG cb;
        hr = pStream->Write(&m_volume, sizeof (m_volume), &cb);
        if (FAILED(hr)) return hr;

        hr = m_speech.WriteToStream (pStream);
        return hr;
    }

    STDMETHODIMP GetSizeMax(ULARGE_INTEGER* pcbSize) {
        if (NULL == pcbSize) return E_POINTER;
        // Length of m_name
        pcbSize->QuadPart = CComBSTR::GetStreamSize(m_name);
        pcbSize->QuadPart += sizeof (m_volume);
        // Length of m_speech
        pcbSize->QuadPart += CComBSTR::GetStreamSize(m_speech);
        return S_OK;
    }

    STDMETHODIMP InitNew() { return S_OK; }
};

IStorage and IPersistStorage

An embeddable objectan object that you can store in an OLE linking and embedding container such as Microsoft Word and Microsoft Excelmust implement IPersistStorage. The container provides the object with an IStorage interface pointer. The IStorage references a structured storage medium. The storage object (the object implementing the IStorage interface) acts much like a directory object in a traditional file system. An object can use the IStorage interface to create new and open existing substorages and streams within the storage medium that the container provides.

interface IStorage : public IUnknown {
  HRESULT CreateStream([string,in] const OLECHAR* pwcsName,
    [in] DWORD grfMode, [in] DWORD reserved1,
    [in] DWORD reserved2,
    [out] IStream** ppstm);

  HRESULT OpenStream([string,in] const OLECHAR* pwcsName,
    [unique][in] void* reserved1, [in] DWORD grfMode,
    [in] DWORD reserved2, [out] IStream** ppstm);

  HRESULT CreateStorage([string,in] const OLECHAR* pwcsName,
    [in] DWORD grfMode, [in] DWORD reserved1,
    [in] DWORD reserved2,
    [out] IStorage** ppstg);

  HRESULT OpenStorage(
    [string,unique,in] const OLECHAR* pwcsName,
    [unique,in] IStorage* pstgPriority,
    [in] DWORD grfMode, [unique,in] SNB snbExclude,
    [in] DWORD reserved, [out] IStorage** ppstg);

  // Following methods abbreviated for clarity...
  HRESULT CopyTo( ... );
  HRESULT MoveElementTo( ... )
  HRESULT Commit( ... )
  HRESULT Revert(void);
  HRESULT EnumElements( ... );
  HRESULT DestroyElement( . ., );
  HRESULT RenameElement( ... );
  HRESULT SetElementTimes( ... );
  HRESULT SetClass( ... );
  HRESULT SetStateBits( ... );
  HRESULT Stat( ... );
};

interface IPersistStorage : public IPersist {
  HRESULT IsDirty ();
  HRESULT InitNew ([unique,in] IStorage* pStg);
  HRESULT Load ([unique,in] IStorage* pStg);
  HRESULT Save ([unique,in] IStorage* pStgSave,
    [in] BOOL fSameAsLoad);
  HRESULT SaveCompleted ([unique,in] IStorage* pStgNew);
  HRESULT HandsOffStorage ();
};

The IsDirty, InitNew, Load, and Save methods work much as the similarly named methods in the persistence interfaces you’ve seen previously. However, unlike streams, when a container hands an object an IStorage during the InitNew or Load calls, the object can hold on to the interface pointer (after AddRef-ing it, of course). This permits the object to read and write its state incrementally instead of all at once, as do the other persistence mechanisms. A container uses the HandsOffStorage and SaveCompleted methods to instruct the object to release the held interface and to give the object a new IStorage interface, respectively.

Typically, a container of embedded objects creates a storage to hold the objects. In this storage, the container creates one or more streams to hold the container’s own state. In addition, for each embedded object, the container creates a substorage in which the container asks the embedded object to save its state.

This is a pretty heavy-weight persistence technique for many objects. Simple objects, such as in the Demagogue example used so far, don’t really need this flexibility. Often, such objects simply create a stream in their given storage and save their state into the stream using an implementation of IPersistStreamInit. This is exactly what the ATL implementation of IPersistStorage does, so I defer creating a custom example here; you’ll see the ATL implementation shortly.

ATL Persistence Implementation Classes

ATL provides implementations of the IPersistPropertyBag. IPersistStreamInit and IPersistStorage interfaces called IPersistPropertyBagImpl, IPersistStreamInitImpl, and IPersistStorageImpl, respectively. Each template class takes one parameter, the name of the deriving class. You add support for these three persistence interfaces to your object like this:

class ATL_NO_VTABLE CDemagogue :
    public IPersistPropertyBagImpl<CDemagogue>,
    public IPersistStreamInitImpl<CDemagogue>,
    public IPersistStorageImpl<CDemagogue> {
 ...
 BEGIN_COM_MAP(CDemagogue)
     ...
     COM_INTERFACE_ENTRY2(IPersist, IPersistPropertyBag)
     COM_INTERFACE_ENTRY(IPersistPropertyBag)
     COM_INTERFACE_ENTRY(IPersistStreamInit)
     COM_INTERFACE_ENTRY(IPersistStream)
     COM_INTERFACE_ENTRY(IPersistStorage)
 END_COM_MAP()
     ...
};

Don’t forget to add the COM MAP enTRy for IPersist. All three persistence interfaces derive from IPersist, not IUnknown, so you need to respond affirmatively to queries for IPersist. Note also that you need to use the COM_INTERFACE_ENTRY2 (or COM_INTERFACE_ENTRY_IID) macro because multiple base classes derive from IPersist.

The Property Map

The ATL implementation of these three persistence interfaces requires that your object provide a table that describes all the properties that should be saved and loaded during a persistence operation. This table is called the property map. ATL uses the property map of a class for two independent purposes: persistence support and control property page support (discussed in Chapter 11, “ActiveX Controls”).

The various property map entries enable you to do the following:

• Define the properties of the COM object that the ATL persistence-implementation classes save and restore during a persistence request

• Define the member variables of the C++ class that the ATL persistence-implementation classes save and restore during a persistence request

• Define the property pages that a class uses

• Associate a property with its property page

The CDemagogue class’s property map looks like this:

BEGIN_PROP_MAP(CDemagogue)
  PROP_ENTRY_EX("Speech", DISPID_SPEECH,
    CLSID_NULL, IID_ISpeaker)
  PROP_ENTRY_EX("Volume", DISPID_VOLUME,
    CLSID_NULL, IID_ISpeaker)
  PROP_ENTRY_EX("Name", DISPID_NAME,
    CLSID_NULL, IID_INamedObject)
END_PROP_MAP()

The BEGIN_PROP_MAP and END_PROP_MAP macros define a class’s property map. You list the persistent properties of an object in the property map using the PROP_ENTRY and PROP_ENTRY_EX macros. The PROP_ENTRY macro describes a property that the persistence implementation can access via the default dispatch interfacein other words, the interface retrieved when you query for IID_IDispatch. You use the PROP_ENTRY_EX macro to describe a property that the persistence implementation must access using some other specified dispatch interface. Both macros require the name of the property, the property’s DISPID, and the CLSID of the property’s associated property page (discussed in Chapter 11). The PROP_ENTRY_EX macro also requires the IID of the dispatch interface that supports the specified property; the PROP_ENTRY macro uses IID_IDispatch.

PROP_ENTRY (szDesc, dispid, clsid)
PROP_ENTRY_EX (szDesc, dispid, clsid, iidDispatch)
PROP_DATA_ENTRY (szDesc, member, vt)

You might also want to load and save member variables of your object that are not accessible via a dispatch interface. The PROP_DATA_ENTRY macro enables you to specify the name of a property, the member variable containing the value, and the VARIANT type of the variable, like so:

BEGIN_PROP_MAP(CBullsEye)
  PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
  PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
  ...
END_PROP_MAP()

Effectively, the PROP_DATA_ENTRY macro causes the persistence implementation to reach into your object, access the specified member variable for the length implied by the VARIANT type, place the data into a VARIANT, and write the VARIANT to the persistent medium. This is quite handy when you have a member variable that is a VARIANT-compatible type. However, it doesn’t work for noncompatible types such as indexed properties. Note that a PROP_PAGE macro also is used to associate aproperty to a property page; I discuss its use in Chapter 11, “ActiveX Controls.” The persistence implementations skip entries in the property map made with the PROP_PAGE macro.

One caution: Don’t add a PROP_ENTRY, PROP_ENTRY_EX, or PROP_DATA_ENTRY macro that has a property name with an embedded space character. Some relatively popular containers, such as Visual Basic 6, provide an implementation of IPropertyBag that cannot handle names with embedded spaces.

When you have a member variable that you want to load and save during a persistence operation, and that variable is not a VARIANT-compatible type (for example, an indexed or array variable), the property map mechanism doesn’t help. You have to override the appropriate member functions of the persistence implementation classes, and read and write the variable explicitly. To do this, you need to know the basic structure of the ATL persistence implementation.

The Persistence Implementations

Let’s look at how the persistence implementations work, using the property bag persistence implementation as the example. All persistence implementations are similar.

The Property Map

The property map macros basically add a static member function called GetPropertyMap to your class. GetPropertyMap returns a pointer to an array of ATL_PROPMAP_ENTRY structures. The structure looks like this:

struct ATL_PROPMAP_ENTRY {
    LPCOLESTR szDesc;
    DISPID dispid;
    const CLSID* pclsidPropPage;
    const IID* piidDispatch;
    DWORD dwOffsetData;
    DWORD dwSizeData;
    VARTYPE vt;
};

For example, here’s a property map and the resulting macro expansion:

BEGIN_PROP_MAP(CDemagogue)
    PROP_ENTRY("Speech", DISPID_SPEECH, CLSID_NULL)
    PROP_ENTRY_EX("Name", DISPID_NAME, CLSID_NULL,
      IID_INamedObject)
    PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
END_PROP_MAP()

This property map expands to this:

__if_not_exists(__ATL_PROP_NOTIFY_EVENT_CLASS) {
    typedef ATL::_ATL_PROP_NOTIFY_EVENT_CLASS
        __ATL_PROP_NOTIFY_EVENT_CLASS;
}
static ATL::ATL_PROPMAP_ENTRY* GetPropertyMap() {
  static ATL::ATL_PROPMAP_ENTRY pPropMap[] = {
  {OLESTR("Speech"), DISPID_SPEECH, &CLSID_NULL,
      __uudiof(IID_IDispatch), 0, 0, 0},
  {OLESTR("Name"), DISPID_ NAME, &CLSID_NULL,
      &IID_INamedObject, 0, 0, 0},
  {OLESTR("_cx"), 0, &CLSID_NULL, NULL,
      offsetof(_PropMapClass, m_sizeExtent.cx),
      sizeof(((_PropMapClass*)0)-> m_sizeExtent.cx), VT_UI4},
  {NULL, 0, NULL, &IID_NULL, 0, 0, 0}
  };
  return pPropMap;
}

The szDesc field of the structure holds the name of the property. It’s used only by the property bag persistence implementation.

The dispid field contains the property’s dispatch identifier. All the persistence implementations need this so they can access the property via one of the object’s IDispatch implementations by calling the Invoke method.

The pclsidPropPage field contains a pointer to the CLSID for the property page associated with the object. It’s not used during persistence.

The piidDispatch field contains a pointer to the IID of the dispatch interface that supports this property. The specified dispid is unique to this interface.

Only PROP_DATA_ENTRY macros use the last three fields. The dwOffsetData field contains the offset of the specified member variable from the beginning of a class instance. The dwSizeData field contains the size of the variable in bytes, and the vt field contains the variable’s VARTYPE (VARIANT type enumeration code).

The various persistence implementations basically iterate over this map and load or save the properties listed. For properties listed using PROP_ENTRY and PROP_ENTRY_EX, the implementations call IDispatch::Invoke with the specified dispid to get or put the property.

Invoke transfers each property via a VARIANT. The stream persistence implementation simply wraps the variant in a CComVARIANT instance and uses its ReadFromStream and WriteToStream methods to do all the hard work. Therefore, stream persistence supports all VARIANT types that the CComVARIANT persistence implementation supports (discussed in Chapter 3, “ATL Smart Types”). The property bag implementation has it even easier because property bags deal directly in VARIANT s.

For properties listed using the PROP_DATA_ENTRY macro, things aren’t quite so simple. The IPersistStreamInit implementation directly accesses the object instance at the specified offset for the specified length. This reads or writes the specified number of bytes directly to or from the object.

However, the IPersistPropertyBag implementation must read and write properties held in a VARIANT. Therefore, this implementation copies the member variable of the object to a VARIANT before writing the property to the bag, and copies a VARIANT to the member variable after reading the property from the bag. The current implementation of IPersistPropertyBag persistence supports only a limited set of VARIANT types; worse, it silently fails to load and save properties with any VARTYPE s other than these:

• VT_UI1, VT_I1: Read and write the variable as a BYTE.

• VT_BOOL: Reads and writes the variable as a VARIANT_BOOL.

• VT_UI2, VT_I2: Read and write the variable as a short.

• VT_UI4, VT_I4, VT_INT, VT_UINT: Read and write the variable as a long.

• VT_BSTR: Reads and writes the variable as a BSTR.

• Any other VT_*: Silently fail.

IPersistPropertyBagImpl

The IPersistPropertyBagImpl<T> class implements the IPersistPropertyBag interface methods. IPersistPropertyBag, like all the persistence interfaces, derives from IPersist, which has one method: GetClassID.

interface IPersist : IUnknown
{ HRESULT GetClassID([out] CLSID* pclsid); }

All the persistence-implementation classes have the same implementation of GetClassID. They call a static member function named GetObjectCLSID method to retrieve the CLSID. This method must be in the deriving class (your object’s class) or one of its base classes.

template <class T>
class ATL_NO_VTABLE IPersistPropertyBagImpl
    : public IPersistPropertyBag {
public:
    ...
    STDMETHOD(GetClassID)(CLSID *pClassID) {
        ATLTRACE(atlTraceCOM, 2, _T("IPersistPropertyBagImpl::GetClassID\n"));
        if (pClassID == NULL)
            return E_POINTER;
        *pClassID = T::GetObjectCLSID();
        return S_OK;
    }};

Normally, your class obtains its GetObjectCLSID static member function from CComCoClass:

template <class T, const CLSID* pclsid = &CLSID_NULL>
class CComCoClass {
public:
    ...
    static const CLSID& WINAPI GetObjectCLSID() {return *pclsid;}
};

This implies that a class must be createable for it to use the persistence classes. This is reasonable because it doesn’t do much good to save a class to some persistent medium and then be unable to create a new instance when loading the object from that medium.

The IPersistPropertyBagImpl<T> class also implements the remaining IPersistPropertyBag methods, including, for example, the Load method. IPersistPropertyBagImpl<T>::Load calls T::IPersistPropertyBag_Load to do most of the work. This allows your class to provide this method when it needs a custom implementation of Load. Normally, your object (class T) doesn’t provide an IPersistPropertyBag_Load method, so this call vectors to a default implementation provided by the base class IPersistPropertyBagImpl<T>::IPersistPropertyBag_Load method. The default implementation calls the global function AtlIPersistPropertyBag_Load. This global function iterates over the property map and, for each entry in the map, loads the property from the property bag:

template <class T>
class ATL_NO_VTABLE IPersistPropertyBagImpl
    : public IPersistPropertyBag {
public:
    ...
    // IPersistPropertyBag
    //
    STDMETHOD(Load)(LPPROPERTYBAG pPropBag,
        LPERRORLOG pErrorLog) {
        ATLTRACE(atlTraceCOM, 2, _T("IPersistPropertyBagImpl::Load\n"));
        T* pT = static_cast<T*>(this);
        ATL_PROPMAP_ENTRY* pMap = T::GetPropertyMap();
        ATLASSERT(pMap != NULL);
        return pT->IPersistPropertyBag_Load(pPropBag,
            pErrorLog, pMap);
    }
    HRESULT IPersistPropertyBag_Load(LPPROPERTYBAG pPropBag,
        LPERRORLOG pErrorLog, ATL_PROPMAP_ENTRY* pMap) {
        T* pT = static_cast<T*>(this);
        HRESULT hr = AtlIPersistPropertyBag_Load(pPropBag,
            pErrorLog, pMap, pT, pT->GetUnknown());
        if (SUCCEEDED(hr))
            pT->m_bRequiresSave = FALSE;
        return hr;
    }
    ...
};

This implementation structure provides three places where we can override methods and provide custom persistence support for a non-VARIANT-compatible property. We can override the Load method itself, in effect directly implementing the IPersistPropertyBag method. Alternatively, we can let ATL implement Load while our object implements IPersistPropertyBag_Load. Finally, we can let ATL implement Load and IPersistPropertyBag_Load while we provide a replacement global function called AtlIPersistPropertyBag_Load and play some linker tricks so that our object uses our global function instead of the ATL-provided one.

The most natural method is to implement Load. Normally, in this implementation, you call the base class Load method to read all properties described in the property map, and then read any custom, non-VARIANT-compatible properties:

HRESULT CMyObject::Load(LPPROPERTYBAG pPropBag,
    LPERRORLOG pErrorLog) {
    HRESULT hr =
IPersistPropertyBagImpl<CMyObject>::Load(pPropBag,pErrorLog);
    if (FAILED (hr)) return hr;

    // Read an array of VT_I4
    // This requires us to create a "name" for each array element
    // Read each element as a VARIANT, then re-create the array
    ...
}

This approach has a few disadvantages. It’s a minor point, but the object now requires four methods for its persistence implementation: its Load, the base class Load, the base class IPersistPropertyBag_Load, and the AtlIPersistPropertyBag_Load. We could copy the base class Load implementation into the object’s Load method, but that makes the object more fragile because future versions of ATL might change its persistence-implementation technique.

Another slight disadvantage to this approach is that it is clear from the ATL implementation that the ATL designers intended for your object to override IPersistPropertyBag_Load. Note the following code fragment from the default implementation of Load:

STDMETHOD(Load)(LPPROPERTYBAG pPropBag, LPERRORLOG pErrorLog) {
  ...
  T* pT = static_cast<T*>(this);
  ...
  return pT->IPersistPropertyBag_Load(pPropBag, pErrorLog, pMap);
}

Instead of directly calling IPersistPropertyBag_Load, which is present in the same class as the Load method, the code calls the method using a pointer to the deriving classyour object’s class. This provides the same functionality as making the method virtual, without the overhead of a virtual function.

Generally, the best solution is to let the object provide its own implementation of the IPersistPropertyBag_Load method. In this implementation, the object can call the global function AtlIPersistProperyBag_Load and save any non-VARIANT-compatible properties it possessed. Here’s an example from the BullsEye control described in Chapter 11, “ActiveX Controls.” It contains a property that is an array of long integers. This can’t be described as a VARIANT-compatible type because it’s not a SAFEARRAY, so I can’t list the property in the property map.

HRESULT CBullsEye::IPersistPropertyBag_Load(
    LPPROPERTYBAG pPropBag, LPERRORLOG pErrorLog,
    ATL_PROPMAP_ENTRY* pMap) {
    if (NULL == pPropBag) return E_POINTER;

    // Load the properties described in the PROP_MAP
    HRESULT hr = AtlIPersistPropertyBag_Load(pPropBag, pErrorLog,
       pMap, this, GetUnknown());
    if (SUCCEEDED(hr)) m_bRequiresSave = FALSE;

    if (FAILED (hr)) return hr;

    // Load the indexed property - RingValues
    // Get the number of rings
    short sRingCount;
    get_RingCount (&sRingCount);
    // For each ring, read its value
    for (short nIndex = 1; nIndex <= sRingCount; nIndex++) {

        // Create the base property name
        CComBSTR bstrName = OLESTR("RingValue");

        // Create ring number as a string
        CComVariant vRingNumber = nIndex;
        hr = vRingNumber.ChangeType (VT_BSTR);
        ATLASSERT (SUCCEEDED (hr));

        // Concatenate the two strings to form property name
        bstrName += vRingNumber.bstrVal;

        // Read ring value from the property bag
        CComVariant vValue = 0L;
        hr = pPropBag->Read(bstrName, &vValue, pErrorLog);
        ATLASSERT (SUCCEEDED (hr));
        ATLASSERT (VT_I4 == vValue.vt);

        if (FAILED (hr)) {
            hr = E_UNEXPECTED;
            break;
        }

        // Set the ring value
        put_RingValue (nIndex, vValue.lVal);
     }

     if (SUCCEEDED(hr)) m_bRequiresSave = FALSE;
     return hr;
 }

The Save method works symmetrically. The IPersistPropertyBagImpl<T> class implements the Save method. IPersistPropertyBagImpl<T>::Save calls T::IPersistPropertyBag_Save to do the work. Again, your object (class T) doesn’t normally provide an IPersistPropertyBag_Save method, so this call vectors to a default implementation that the base class IPersistPropertyBagImpl<T>::IPersistPropertyBag_Save method provides. The default implementation calls the global function AtlIPersistPropertyBag_Save. This global function iterates over the property map and, for each entry in the map, saves the property to the property bag.

template <class T>
class ATL_NO_VTABLE IPersistPropertyBagImpl
    : public IPersistPropertyBag {
public:
    ...
    // IPersistPropertyBag
    //
    STDMETHOD(Save)(LPPROPERTYBAG pPropBag, BOOL fClearDirty,
        BOOL fSaveAllProperties) {
        ATLTRACE(atlTraceCOM, 2, _T("IPersistPropertyBagImpl::Save\n"));
        T* pT = static_cast<T*>(this);
        ATL_PROPMAP_ENTRY* pMap = T::GetPropertyMap();
        ATLASSERT(pMap != NULL);
        return pT->IPersistPropertyBag_Save(pPropBag,
            fClearDirty, fSaveAllProperties, pMap);
    }

    HRESULT IPersistPropertyBag_Save(LPPROPERTYBAG pPropBag,
    BOOL fClearDirty, BOOL fSaveAllProperties,
        ATL_PROPMAP_ENTRY* pMap) {
        T* pT = static_cast<T*>(this);
        HRESULT hr;
        hr = AtlIPersistPropertyBag_Save(pPropBag, fClearDirty,
            fSaveAllProperties, pMap, pT, pT->GetUnknown());
        if (fClearDirty && SUCCEEDED(hr)) {
            pT->m_bRequiresSave=FALSE;
        }
        return hr;
    }
};

Finally, IPersistPropertyBagImpl implements the InitNew method this way:

STDMETHOD(InitNew)() {
    ATLTRACE(atlTraceCOM, 2,
        _T("IPersistPropertyBagImpl::InitNew\n"));
    T* pT = static_cast<T*>(this);
    pT->m_bRequiresSave = TRUE;
    return S_OK;
}

Therefore, you need to override InitNew directly when you have any initialization to perform when there are no properties to load.

IPersistStreamInitImpl

The implementation contained in IPersistStreamInitImpl is quite similar to the one just described. The Load and Save methods call the IPersistStreamInit_Load and IPersistStreamInit_Save methods, which are potentially provided by the deriving object but typically provided by the default implementation in IPersistStreamInitImpl. These implementations call the global helper functions AtlIPersistStreamInit_Load and AtlIPersistStreamInit_Save.

template <class T>
class ATL_NO_VTABLE IPersistStreamInitImpl
  : public IPersistStreamInit {
public:
  ...
  // IPersistStream
  STDMETHOD(Load)(LPSTREAM pStm) {
    ATLTRACE(atlTraceCOM, 2,
      _T("IPersistStreamInitImpl::Load\n"));
    T* pT = static_cast<T*>(this);
    return pT->IPersistStreamInit_Load(pStm,
      T::GetPropertyMap());
  }

  HRESULT IPersistStreamInit_Load(LPSTREAM pStm,
    ATL_PROPMAP_ENTRY* pMap) {
    T* pT = static_cast<T*>(this);
    HRESULT hr =
      AtlIPersistStreamInit_Load(pStm, pMap, pT,
        pT->GetUnknown());
    if (SUCCEEDED(hr)) pT->m_bRequiresSave = FALSE;
    return hr;
  }

  STDMETHOD(Save)(LPSTREAM pStm, BOOL fClearDirty) {
    T* pT = static_cast<T*>(this);
    ATLTRACE(atlTraceCOM, 2,
      _T("IPersistStreamInitImpl::Save\n"));
    return pT->IPersistStreamInit_Save(pStm, fClearDirty,
      T::GetPropertyMap());
  }

  HRESULT IPersistStreamInit_Save(LPSTREAM pStm,
    BOOL fClearDirty, ATL_PROPMAP_ENTRY* pMap) {
    T* pT = static_cast<T*>(this);
    return AtlIPersistStreamInit_Save(pStm, fClearDirty,
      pMap, pT, pT->GetUnknown());
  }
};

IPersistStreamInitImpl also implements the InitNew method this way:

STDMETHOD(InitNew)() {
    ATLTRACE(atlTraceCOM, 2,
      _T("IPersistStreamInitImpl::InitNew\n"));
    T* pT = static_cast<T*>(this);
    pT->m_bRequiresSave = TRUE;
  return S_OK;
}

Therefore, as with property bags, you need to override InitNew directly when you have any initialization to perform when there are no properties to load.

The implementation of the IsDirty method assumes the presence of a member variable named m_bRequiresSave somewhere in your class hierarchy.

STDMETHOD(IsDirty)() {
    ATLTRACE(atlTraceCOM, 2,
      _T("IPersistStreamInitImpl::IsDirty\n"));
    T* pT = static_cast<T*>(this);
    return (pT->m_bRequiresSave) ? S_OK : S_FALSE;
}

The persistence implementations originally assumed that only ActiveX controls would use them, as if controls were the only objects that needed a persistence implementation. Although ATL has greatly reduced the coupling between the control classes and the persistence implementation, the CComControlBase class normally provides the m_bRequiresSave variable and the SetDirty and Getdirty helper functions usually used to access the variable.

class ATL_NO_VTABLE CComControlBase {
public:
    void SetDirty(BOOL bDirty) { m_bRequiresSave = bDirty; }

    // Obtain the dirty state for the control
    BOOL GetDirty() { return m_bRequiresSave; }
    ...
    unsigned m_bRequiresSave:1;
};

To use the persistence-implementation classes in an object that doesn’t derive from CComControlBase, you need to define the m_bRequiresSave variable in your class hierarchy somewhere. Typically, for convenience, you also define the SetDirty and Getdirty helper methods. Noncontrols can use this class to provide this persistence support:

class ATL_NO_VTABLE CSupportDirtyBit {
public:
  CSupportDirtyBit() : m_bRequiresSave(FALSE) {}
  void SetDirty(BOOL bDirty) {
    m_bRequiresSave = bDirty ? TRUE : FALSE;
  }
  BOOL GetDirty() { return m_bRequiresSave ? TRUE : FALSE; }
  BOOL m_bRequiresSave;
};

Finally, the IPersistStreamInitImpl class provides the following implementation of GetSizeMax:

STDMETHOD(GetSizeMax)(ULARGE_INTEGER* pcbSize) {
  HRESULT hr = S_OK;
  T* pT = static_cast<T*>(this);

  if (pcbSize == NULL)
    return E_POINTER;

  ATL_PROPMAP_ENTRY* pMap = T::GetPropertyMap();
  ATLENSURE(pMap != NULL);

  // Start the size with the size of the ATL version
  // we write out.
  ULARGE_INTEGER nSize;
  nSize.HighPart = 0;
  nSize.LowPart = sizeof(DWORD);

  CComPtr<IDispatch> pDispatch;
  const IID* piidOld = NULL;
  for (int i = 0; pMap[i].pclsidPropPage != NULL; i++) {
    if (pMap[i].szDesc == NULL)
      continue;

    // check if raw data entry
    if (pMap[i].dwSizeData != 0) {
      ULONG ulSize=0;
      //Calculate stream size for BSTRs special case
      if (pMap[i].vt == VT_BSTR) {
        void* pData = (void*)(pMap[i].dwOffsetData +
          (DWORD_PTR)pT);
        ATLENSURE(
          pData >= (void*)(DWORD_PTR)pMap[i].dwOffsetData
          && pData >= (void*)(DWORD_PTR)pT );
        BSTR bstr=*reinterpret_cast<BSTR*>(pData);
        ulSize=CComBSTR::GetStreamSize(bstr);
      } else {
        ulSize = pMap[i].dwSizeData;
      }
      nSize.QuadPart += ulSize;
      continue;
    }

    CComVariant var;
    if (pMap[i].piidDispatch != piidOld) {
      pDispatch.Release();
      if (FAILED(pT->GetUnknown()->
        QueryInterface(*pMap[i].piidDispatch,
        (void**)&pDispatch))) {
        ATLTRACE(atlTraceCOM, 0,
          _T("Failed to get a dispatch pointer for "
             "property #%i\n"), i);
        hr = E_FAIL;
        break;
      }
      piidOld = pMap[i].piidDispatch;
    }

    if (FAILED(pDispatch.GetProperty(pMap[i].dispid, &var))) {
      ATLTRACE(atlTraceCOM, 0,
        _T("Invoked failed on DISPID %x\n"),
        pMap[i].dispid);
      hr = E_FAIL;
      break;
    }
    nSize.QuadPart += var.GetSize();
  }
  *pcbSize = nSize;
  return hr;
}

Previous versions of ATL simply returned E_NOTIMPL from the GetSizeMax function. As of this writing, the MSDN documentation claims that ATL still does not implement this function. In any event, the implementation that ATL 8 actually provides is fairly straightforward. GetSizeMax loops through all the entries in the property map and accumulates the total size each entry requires in the nSize variable. If it finds a “raw”PROP_DATA_ENTRY, it simply increments the total nSize by the size ofthe member specified in the PROP_DATA_ENTRY macro. Alternatively, if it finds a PROP_ENTRY or PROP_ENTRY_EX in the map, it queries the object for the specified IDispatch interface and wraps the resulting interface pointer in a CComPtr. Recall from Chapter 3, “ATL Smart Types,” that the CComPtr smart pointer template class provides a convenient specialization for IDispatch that exposes property “getters” and “setters.”GetSizeMax uses CComPtr<IDispatch>::GetProperty to retrieve a VARIANT value for the property specified in the property map entry. The function wraps the returned VARIANT in a CComVariant and uses that class’s GetSize function to increment the nSize total for the object.

IPersistStorageImpl

The ATL implementation of IPersistStorage is very simplistic. The Save method creates a stream called "Contents" within the provided storage and depends on an IPersistStreamInit implementation to write the contents of the stream.

template <class T>
class ATL_NO_VTABLE IPersistStorageImpl
    : public IPersistStorage {
public:
    STDMETHOD(Save)(IStorage* pStorage, BOOL fSameAsLoad) {
        ATLTRACE(atlTraceCOM, 2,
          _T("IPersistStorageImpl::Save\n"));
        CComPtr<IPersistStreamInit> p;
        p.p = IPSI_GetIPersistStreamInit();
        HRESULT hr = E_FAIL;
        if (p != NULL) {
            CComPtr<IStream> spStream;
            static LPCOLESTR vszContents = OLESTR("Contents");
            hr = pStorage->CreateStream(vszContents,
              STGM_READWRITE | STGM_SHARE_EXCLUSIVE | STGM_CREATE,
              0, 0, &spStream);
            if (SUCCEEDED(hr)) hr = p->Save(spStream, fSameAsLoad);
        }
        return hr;
    }
    ...
};

Similarly, the Load method opens the "Contents" stream and uses the IPersistStreamInit implementation to read the contents of the stream.

STDMETHOD(Load)(IStorage* pStorage) {
    ATLTRACE(atlTraceCOM, 2, _T("IPersistStorageImpl::Load\n"));
    CComPtr<IPersistStreamInit> p;
    p.p = IPSI_GetIPersistStreamInit();
    HRESULT hr = E_FAIL;
    if (p != NULL) {
        CComPtr<IStream> spStream;
        hr = pStorage->OpenStream(OLESTR("Contents"), NULL,
          STGM_DIRECT | STGM_SHARE_EXCLUSIVE, 0, &spStream);
        if (SUCCEEDED(hr)) hr = p->Load(spStream);
    }
    return hr;
}

The InitNew and IsDirty implementations retrieve the object’s IPersistStreamInit interface pointer (using a helper function to get the interface) and delegate to the same named method in that interface:

STDMETHOD(IsDirty)(void) {
    ATLTRACE(atlTraceCOM, 2,
      _T("IPersistStorageImpl::IsDirty\n"));
    CComPtr<IPersistStreamInit> p;
    p.p = IPSI_GetIPersistStreamInit();
    return (p != NULL) ? p->IsDirty() : E_FAIL;
}

STDMETHOD(InitNew)(IStorage*) {
    ATLTRACE(atlTraceCOM, 2,
      _T("IPersistStorageImpl::InitNew\n"));
    CComPtr<IPersistStreamInit> p;
    p.p = IPSI_GetIPersistStreamInit();
    return (p != NULL) ? p->InitNew() : E_FAIL;
}

One of the main reasons an object supports IPersistStorage is so the object can incrementally read and write its state. Unfortunately, the ATL implementation doesn’t support this. The implementation does not cache the provided IStorage interface provided during the Load and Save calls, so it’s not available for later incremental reads and writes. Not caching the IStorage interface makes implementing the last two methods trivial, however:

STDMETHOD(SaveCompleted)(IStorage* /* pStorage */) {
  ATLTRACE(atlTraceCOM, 2,
    _T("IPersistStorageImpl::SaveCompleted\n"));
  return S_OK;
}

STDMETHOD(HandsOffStorage)(void) {
  ATLTRACE(atlTraceCOM, 2, _T("IPersistStorageImpl::HandsOffStorage\n"));
  return S_OK;
}

Generally, most objects that need the functionality IPersistStorage provides can’t use the implementation ATL provides. They must derive directly from IPersistStorage and implement all the methods explicitly.

Additional Persistence Implementations

Given what you’ve already seen, you might find it interesting to demonstrate an additional persistence implementation built using functionality we’ve already covered.

IPersistMemory

Let’s look at implementing the IPersistMemory interface:

interface IPersistMemory : IPersist {
    HRESULT IsDirty();
    HRESULT Load([in, size_is(cbSize)] LPVOID pvMem,
        [in] ULONG cbSize);
    HRESULT Save([out, size_is(cbSize)] LPVOID pvMem,
        [in] BOOL fClearDirty, [in] ULONG cbSize);
    HRESULT GetSizeMax([out] ULONG* pCbSize);
    HRESULT InitNew();
};

The IPersistMemory interface allows a client to request that the object save its state to a fixed-size memory block (identified with a void*). The interface is very similar to IPersistStreamInit, except that it uses a memory block instead of an expandable IStream. The cbSize argument to the Load and Save methods indicates the amount of memory accessible through pvMem. The IsDirty, GetSizeMax, and InitNew methods are semantically identical to those in IPersistStreamInit.

Implementing the IPersistMemory interface

You’ve seen that ATL provides the IPersistStreamInitImpl class that saves and restores the state of an object to a stream. The COM API CreateStreamOnHGlobal returns an IStream implementation that reads and writes to a global memory block. We can use the two together and easily implement IPersistMemory using the functionality IPersistStreamInitImpl provides.

With the exception of the Load and Save methods, all methods in our IPersistMemory implementation simply delegate to the same named method in ATL’s IPersistStreamInit implementation.

template <class T, class S = IPersistStreamInit>
class ATL_NO_VTABLE IPersistMemoryImpl : public IPersistMemory {
public:
    // IPersist
    STDMETHODIMP GetClassID(CLSID *pClassID) {
        ATLTRACE(atlTraceCOM, 2, _T("IPersistMemoryImpl::GetClassID\n"));
        T* pT = static_cast<T*>(this);
        S* psi = static_cast <S*> (pT);
        return psi->GetClassID(pClassID);
    }

    // IPersistMemory
    STDMETHODIMP IsDirty() {
        ATLTRACE(atlTraceCOM, 2,
            _T("IPersistMemoryImpl::IsDirty\n"));
        T* pT = static_cast<T*>(this);
        S* psi = static_cast <S*> (pT);
        return psi->IsDirty();
    }

    STDMETHODIMP Load(void* pvMem, ULONG cbSize) {
        ATLTRACE(atlTraceCOM, 2,
            _T("IPersistMemoryImpl::Load\n"));
        T* pT = static_cast<T*>(this);

        // Get memory handle. We need an actual HGLOBAL
        // here because it's required for CreateStreamOnHGlobal
        HGLOBAL h = GlobalAlloc(GMEM_MOVEABLE, cbSize);
        if (h == NULL) return E_OUTOFMEMORY;
        LPVOID pv = GlobalLock(h);
        if (!pv) return E_OUTOFMEMORY;

        // Copy to memory block
        CopyMemory (pv, pvMem, cbSize);
        CComPtr<IStream> spStrm;
        // Create stream on memory
        HRESULT hr = CreateStreamOnHGlobal (h, TRUE, &spStrm);
        if (FAILED (hr)) {
            GlobalUnlock (h);
            GlobalFree (h);
            return hr;
        }
        // Stream now owns the memory

        // Load from stream
        S* psi = static_cast <S*> (pT);
        hr = psi->Load (spStrm);

        GlobalUnlock (h);
        return hr;
    }

    STDMETHODIMP Save(void* pvMem, BOOL fClearDirty,
        ULONG cbSize) {
        ATLTRACE(atlTraceCOM, 2,
            _T("IPersistMemoryImpl::Save\n"));
        T* pT = static_cast<T*>(this);

        // Get memory handle
        HGLOBAL h = GlobalAlloc (GMEM_MOVEABLE, cbSize);
        if (NULL == h) return E_OUTOFMEMORY;

        // Create stream on memory
        CComPtr<IStream> spStrm;
        HRESULT hr = CreateStreamOnHGlobal (h, TRUE, &spStrm);
        if (FAILED (hr)) {
            GlobalFree (h);
            return hr;
        }
        // Stream now owns the memory

        // Set logical size of stream to physical size of memory
        // (Global memory block allocation rounding causes
        // differences)
        ULARGE_INTEGER uli;
        uli.QuadPart = cbSize ;
        spStrm->SetSize (uli);

        S* psi = static_cast <S*> (pT);
        hr = psi->Save (spStrm, fClearDirty);
        if (FAILED (hr)) return hr;

        LPVOID pv = GlobalLock (h);
        if (!pv) return E_OUTOFMEMORY;
        // Copy to memory block
        CopyMemory (pvMem, pv, cbSize);

        return hr;
    }

    STDMETHODIMP GetSizeMax(ULONG* pcbSize) {
        if (pcbSize == NULL) return E_POINTER;
        *pcbSize = 0;

        T* pT = static_cast<T*>(this);
        S* psi = static_cast <S*> (pT);
        ULARGE_INTEGER uli ;
        uli.QuadPart = 0;
        HRESULT hr = psi->GetSizeMax (&uli);
        if (SUCCEEDED (hr)) *pcbSize = uli.LowPart;

        return hr;
    }

    STDMETHODIMP InitNew() {
        ATLTRACE(atlTraceCOM, 2,
            _T("IPersistMemoryImpl::InitNew\n"));
        T* pT = static_cast<T*>(this);
        S* psi = static_cast <S*> (pT);
        return psi->InitNew();
    }
};

Notice the use of static_cast to downcast the this pointer to the deriving class and then up-cast the resulting pointer to an IPersistStreamInit*. We do this so that we get a compile-time error when the class deriving from IPersistMemoryImpl doesn’t also derive from IPersistStreamInit. This approach does require the deriving class to not implement IPersistStreamInit in an “unusual” way, such as on a tear-off interface or via aggregation.

Alternatively, we could have retrieved the IPersistStreamInit interface using QueryInterface:

T* pT = static_cast<T*>(this);
CComQIPtr<S> psi = pT->GetUnknown() ;

However, then we might find out at runtime that no IPersistStreamInit implementation is available, which means the object then ends up saying that it implements IPersistMemory without the capability to do so. I prefer compile-time errors whenever possible, so I chose the former approach accepting its limitations.

Using the IPersistMemoryImpl Template Class

An object uses this IPersistMemory implementation this way:

class ATL_NO_VTABLE CDemagogue :
    ...
    public IPersistStreamInitImpl<CDemagogue>,
    public IPersistMemoryImpl<CDemagogue>,
    public CSupportDirtyBit {
    ...
BEGIN_COM_MAP(CDemagogue)
    ...
    COM_INTERFACE_ENTRY2(IPersist, IPersistStreamInit)
    COM_INTERFACE_ENTRY(IPersistStreamInit)
    COM_INTERFACE_ENTRY(IPersistMemory)
END_COM_MAP()

Adding Marshal-by-Value Semantics Using Persistence

When you pass an interface pointer as a parameter to a remote (out-of-apartment) method call, the default in COM is to pass by reference. In other words, the object stays where it is, and only a reference to the object is given to the recipient of the call. This typically means that references to the object involve round-trips back to the object, which can be quite expensive. An object can override this pass-by-reference default by implementing the IMarshal interface.

The primary reason most developers implement IMarshal on an object is to give it pass-by-value semantics. In other words, when you pass an interface pointer to a remote method call, you prefer that COM pass a copy of the object to the method. All references to the object are then local and do not involve round-trips back to the “original” object. When an object implements IMarshal in such a way that it has pass-by-value semantics, we typically say that the object marshals by value.

interface IMarshal : public IUnknown {
  STDMETHOD GetUnmarshalClass([in] REFIID riid,
    [unique,in] void* pv,
    [in] DWORD dwDestContext,
    [unique,in] void* pvDestContext,
    [in] DWORD mshlflags, [out] CLSID* pCid);

  STDMETHOD GetMarshalSizeMax([in] REFIID riid,
    [unique,in] void* pv,
    [in] DWORD dwDestContext,
    [unique,in] void* pvDestContext,
    [in] DWORD mshlflags,
    [out] DWORD* pSize) ;

  STDMETHOD MarshalInterface([unique,in] IStream* pStm,
    [in] REFIID riid, [unique][in] void* pv,
    [in] DWORD dwDestContext,
    [unique,in] void* pvDestContext,
    [in] DWORD mshlflags);

  STDMETHOD UnmarshalInterface([unique,in] IStream* pStm,
    [in] REFIID riid, [out] void** ppv);

  STDMETHOD ReleaseMarshalData([unique,in] IStream* pStm);

  STDMETHOD DisconnectObject([in] DWORD dwReserved);
};

Given a complete implementation of IPersistStream or IPersistStreamInit, it’s quite easy to build a marshal-by-value implementation of IMarshal.

A class typically implements marshal-by-value by returning its own CLSID as the result of the GetUnmarshalClass method. The IPersistStream::GetClassID method produces the needed CLSID.

The GetMarshalSizeMax method must return the number of bytes needed to save the persistent state of the object into a stream. The IPersistStream::GetSizeMax method produces the needed size.

The MarshalInterface and UnmarshalInterface methods need to write and read, respectively, the persistent state of the object into the provided stream. Therefore, we can use the Save and Load methods of IPersistStream for this functionality.

ReleaseMarshalData and DisconnectObject method can simply return S_OK.

Here’s a template class that uses an object’s IPersistStreamInit interface to provide a marshal-by-value implementation. [1] Once again, I decided to down-cast and up-cast using static_cast to obtain the IPersistStreamInit interface, so I receive an error at compile time when the deriving class doesn’t implement IPersistStreamInit.

[1]

This technique has a history, as does most software development. Jonathon Bordan wrote the first IMarshalByValueImpl after being inspired by a Microsoft System Journal article by Don Box. Brent Rector then modified Jonathon’s example to the present form.

template <class T>
class ATL_NO_VTABLE IMarshalByValueImpl : public IMarshal {

  STDMETHODIMP GetUnmarshalClass(REFIID /* riid */,
    void* /* pv */,
    DWORD /* dwDestContext */,
    void* /* pvDestContext */,
    DWORD /* mshlflags */, CLSID *pCid) {
    T* pT = static_cast<T*>(this);
    IPersistStreamInit* psi =
      static_cast<IPersistStreamInit*>(pT);
    return psi->GetClassID (pCid);
  }

  STDMETHODIMP GetMarshalSizeMax(REFIID /* riid */,
    void* /* pv */,
    DWORD /* dwDestContext */,
    void* /* pvDestContext */,
    DWORD /* mshlflags */, DWORD* pSize) {
    T* pT = static_cast<T*>(this);
    IPersistStreamInit* psi =
      static_cast <IPersistStreamInit*> (pT);

    ULARGE_INTEGER uli = { 0 };

    HRESULT hr = psi->GetSizeMax(&uli);
    if (SUCCEEDED (hr)) *pSize = uli.LowPart;
    return hr;
  }

  STDMETHODIMP MarshalInterface(IStream *pStm, REFIID /* riid */,
    void* /* pv */, DWORD /* dwDestContext */,
    void* /* pvDestCtx */, DWORD /* mshlflags */) {
    T* pT = static_cast<T*>(this);
    IPersistStreamInit* psi = static_cast <IPersistStreamInit*> (pT);
    return psi->Save(pStm, FALSE);
  }

  STDMETHODIMP UnmarshalInterface(IStream *pStm, REFIID riid,
    void **ppv) {
    T* pT = static_cast<T*>(this);
    IPersistStreamInit* psi =
      static_cast <IPersistStreamInit*> (pT);
    HRESULT hr = psi->Load(pStm);
    if (SUCCEEDED (hr)) hr = pT->QueryInterface (riid, ppv);
    return hr;
  }
  STDMETHODIMP ReleaseMarshalData(IStream* /* pStm */) {
    return S_OK;
  }

  STDMETHODIMP DisconnectObject(DWORD /* dwReserved */) {
    return S_OK;
  }
};

You can use this template class to provide a marshal-by-value implementation for your object. You need to derive your class from the previous IMarshalByValueImpl class (to get the IMarshal method implementations) and the IPersistStreamInitImpl class. You must also add a COM_INTERFACE_ENTRY for IMarshal to the class’s interface map. Here’s an example:

class ATL_NO_VTABLE CDemagogue :
    ...
    public IPersistStreamInitImpl<CDemagogue>,
    public CSupportDirtyBit,
    public IMarshalByValueImpl<CDemagogue> {
    ...
  BEGIN_COM_MAP(CDemagogue)
      COM_INTERFACE_ENTRY2(IPersist, IPersistStreamInit)
      COM_INTERFACE_ENTRY(IPersistStreamInit)
      COM_INTERFACE_ENTRY(IMarshal)
  END_COM_MAP()
  ...
};

Note that adding marshal-by-value support to your class this way means that all instances of the class use pass-by-value semantics. It is not possible to pass one object instance by reference and another instance by value (assuming that both instances have the same marshaling context: in-proc, local, or different machine).

Summary

Many objects need some support for persistence, and ATL provides an easily extensible, table-driven implementation of the IPersistStream[Init] and the IPersistPropertyBag interfaces. These implementations save and load the properties described by the class’s property map entries. By overriding the appropriate methods, you can extend this persistence support for data types that property map entries do not support. The ATL implementation of IPersistStorage allows the object to be embedded into an OLE container but doesn’t take advantage of many of the capabilities of the IStorage medium.

Using and extending the stream persistence support that ATL provides allows an object to offer additional functionality to its clients. For example, you’ve seen how to implement IPersistMemory support to your object (which MFC-based containers prefer). In addition, you can easily add marshal-by-value semantics to your class by reusing the stream persistence functionality.