IPersistStorage

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This interface defines methods that enable a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container's storage.

The IPersistStorageinterface defines methods that enable a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container's storage.

The IPersistStoragecontract inherits its definition from IPersist, so all implementations must also include the GetClassIDmethod of IPersist.

When to Implement

Any object that can be embedded in a container must implement the IPersistStorageinterface. This interface is one of the primary interfaces for a compound document object. Embeddable objects must also implement the IOleObjectand IDataObjectinterfaces.

The OLE default handler for embedded objects provides an implementation of the IPersistStorageinterface that is used when the object is in the loaded state. Similarly, the OLE default link handler provides an IPersistStorageimplementation that manages storage for a linked object. These default handlers both interact with the OLE default cache implementation, which has its own IPersistStorageimplementation.

If you are providing a custom embedding or link handler for your objects, the handler must include an implementation of IPersistStorage. You can delegate calls to the default handler so you can take advantage of the default cache implementation.

When to Use

When an OLE container creates a new object, loads an existing object from storage, or inserts a new object in a clipboard or a drag-and-drop operation, the container uses the IPersistStorageinterface to initialize the object and put it in the loaded or running state. When an object is loaded or running, an OLE container calls other IPersistStoragemethods to instruct the object to perform various save operations or to release its storage.

Typically, applications use helper functions such as OleCreate, rather than calling the IPersistStorage::Loador IPersistStorage::InitNewmethods directly. Similarly, applications typically call the OleSavehelper function rather than calling IPersistStorage::Savedirectly.

Method	Description
IPersistStorage::HandsOffStorage	Instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOff mode, in which the object cannot do anything and only the close operation works.
IPersistStorage::InitNew	Initializes a new object, providing a pointer to the storage to be used for the object.
IPersistStorage::IsDirty	Indicates whether the object has changed since it was last saved to its current storage.
IPersistStorage::Load	Loads an object from its existing storage.
IPersistStorage::Save	Saves an object and any nested objects that it contains into the specified storage. The object is placed in NoScribble mode and must not write to the specified storage until it receives a call to its IPersistStorage::SaveCompletedmethod.
IPersistStorage::SaveCompleted	Notifies the object that it can revert from NoScribble or HandsOff mode, in which it must not write to its storage object, to Normal mode, in which it can.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Oleidl.h

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

IPersistStorage:IUnknown