Contents
Previous Topic: IPropertyBag::Write
Next Topic: IPersistPropertyBag2::InitNew
| | |
| ||
| ||
The IPersistPropertyBag2 Interface
The IPersistPropertyBag2 interface works in conjunction with the IPropertyBag2 and IErrorLog interfaces to define an individual property-based persistence mechanism. This interface is similar to IPersistPropertyBag, but allows the object to support property bags that implement IPropertyBag2.
Whereas a mechanism like IPersistStream gives an object an IStream in which to store its binary data, IPersistPropertyBag2 provides an object with an IPropertyBag2 interface through which it can save and load individual properties. The implementor of IPropertyBag2 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 work 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.
When requesting a persistent property bag interface, a property bag that supports IPropertyBag2 will attempt to obtain the object's IPersistPropertyBag2 interface before attempting to obtain the object's IPersistPropertyBag interface. This allows objects that support either interface to communicate with the property bag.
IDL:
[object, uuid(22F55881-280B-11d0-A8A9-00A0C90C2004), pointer_default(unique)] interface IPersistPropertyBag2 : IPersist { typedef [unique] IPersistPropertyBag2 *LPPERSISTPROPERTYBAG2; HRESULT InitNew(); HRESULT Load( [in]IPropertyBag2 * pPropBag, [in]IErrorLog * pErrLog); HRESULT Save( [in]IPropertyBag2 * pPropBag, [in]BOOL fClearDirty, [in]BOOL fSaveAllProperties); HRESULT IsDirty(); }The basic mechanism is that a container tells the object to save or load its properties through IPersistPropertyBag2. For each property, the object calls the container's IPropertyBag2 interface passed to the IPersistPropertyBag members. IPropertyBag2::Write saves a property in whatever place the container wants to put it, and IPropertyBag2::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 retaining itself the decision as to which properties are saved or loaded.
Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
IPersistPropertyBag2::InitNew