IPersistPropertyBag Interface

The IPersistPropertyBag interface works in conjunction with IPropertyBag (see below) and IErrorLog (see below) to define an individual property-based persistence mechanism. Whereas a mechanism such as IPersistStream gives an object an IStream in which to store its binary data, IPersistPropertyBag provides an object with an IPropertyBag interface through which it can save and load individual properties. The implementor of IPropertyBag can then save those properties in whatever way it chooses, such as name/value pairs in a text file. Errors encountered in the process (on either side) are recorded in an "error log" through IErrorLog. This error reporting mechanism works on a per-property basis instead of an "all properties as a whole" basis through just the return value of IPersist*::Load or IPersist*::Save.

IDL:

[
uuid(37D84F60-42CB-11CE-8135-00AA004BB851)
    , object, pointer_default(unique)
]
interface IPersistPropertyBag : IPersist
    {
    HRESULT InitNew(void);
    HRESULT Load([in] IPropertyBag *pPropBag, [in] IErrorLog *pErrorLog);
    HRESULT Save([in] IPropertyBag *pPropBag, [in] BOOL fClearDirty
        , [in] BOOL fSaveAllProperties);
    };

The basic mechanism is that a container tells the object to save or load its properties through IPersistPropertyBag. For each property, the object calls the container's IPropertyBag interface passed to the IPersistPropertyBag members. IPropertyBag::Write obviously saves a property in whatever place the container wants to put it, and IPropertyBag::Read retrieves a property.

This protocol is essentially a means of sequentially communicating individual property values from the object to the container, which is useful for doing save-as-text operations and the like. The object gives the container the choice of the format in which each property is saved, while itself retaining the decision as to which properties are saved or loaded.

IPersistPropertyBag Methods

InitNew	Informs the object that it is being initialized as a newly created object.
Load	Instructs the object to initialize itself using the properties available in the property bag, notifying the provided error log object when errors occur.
Save	Instructs the object to save its properties to the given property bag, optionally clearing the object's "dirty" flag.

Does this content meet your programming needs? Write us!

Back to top