IPersistMoniker

Objects, especially asynchronous-aware objects, can expose the IPersistMoniker interface to obtain more control over the way they bind to their persistent data.

Existing moniker implementations call QueryInterface on the client objectfor persistence interfaces such as IPersistFile, IPersistStream[Init], or IPersistStorage as part of their IMoniker::BindToObject implementation when they are instantiating and initializing the object. The IPersistMoniker interface allows moniker implementations and other applications that instantiate objects from persistent data to give control to the object being instantiated over binding to its persistent data. An object could, for example, implement IPersistMoniker::Load by calling IMoniker::BindToStorage for the interface it prefers: IStorage, IStream, asynchronous binding, etc.

Unlike some other persistent object interfaces, IPersistMoniker does not include an InitNew method. This means that IPersistMoniker cannot be used to initialize an object to a freshly initialized state. Clients of IPersistMoniker who wish to initialize the object should QueryInterface for a different persistence interface that contains an InitNew method, such as IPersistStreamInit, IPersistMemory, or IPersistPropertyBag. Then, the client can use the InitNew method found in the other persistence interface to initialize the object. The client can still safely used IPersistMoniker to save the persistent state of the object.

The IPersistMoniker contract inherits its definition from the IPersist interface, and includes the GetClassID method of IPersist.

When to Implement

Implement IPersistMoniker on any object that can be saved persistently to multiple storage mediums or can take advantage of any of the asynchronous stream, storage, or IMoniker::BindToStorage behavior described above.

When to Use

Custom moniker implementations should support IPersistMoniker as the most flexible persistence interface in their implementation of IMoniker::BindToObject if they are instantiating an arbitrary class and need to initialize it from persistent data. Typically, these monikers should use the published persistence interfaces in the following order: IPersistMoniker, IPersistStream[Init], IPersistStorage, IPersistFile, and IPersistMemory.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the object.

IPersistMoniker Methods	Description
IsDirty	Checks an object for changes since it was last saved.
Load	Loads an object using a specified moniker.
Save	Saves the object, specifying a destination moniker.
SaveCompleted	Notifies the object that the save operation is complete.
GetCurMoniker	Gets the current moniker for the object.