Persistence Interfaces
Objects that have a persistent state of any kind must implement at least one IPersist* interface, and preferably multiple interfaces, in order to provide the container with the most flexible choice of how it wishes to save a control's state.
If a control has any persistent state whatsoever, it must, as a minimum, implement either IPersistStream or IPersistStreamInit (the two are mutually exclusive and shouldn't be implemented together for the most part). The latter is used when a control wishes to know when it is created new as opposed to reloaded from an existing persistent state (IPersistStream does not have the created new capability). The existence of either interface indicates that the control can save and load its persistent state into a stream, that is, an instance of IStream.
Beyond these two stream-based interfaces, the IPersist* interfaces listed in the following table can be optionally provided in order to support persistence to locations other than an expandable IStream.
A set of component categories is identified to cover the support for persistency interfaces see Component Categories.
| Interface | Usage |
|---|---|
| IPersistMemory |
The object can save and load its state into a fixed-length sequential byte array (in memory). |
| IPersistStorage |
The object can save and load its state into an IStorage instance. Controls that wish to be marked Insertable as other compound document objects (for insertion into non-control aware containers) must support this interface. |
| IPersistPropertyBag |
The object can save and load its state as individual properties written to IPropertyBag which the container implements. This is used for Save As Text functionality in some containers. |
| IPersistMoniker |
The object can save and load its state to a location named by a moniker. The control calls IMoniker::BindToStorage to retrieve the storage interface it requires, such as IStorage, IStream, ILockBytes, IDataObject, etc. |
While support for IPersistPropertyBag is optional, it is strongly recommended as an optimization for containers with Save As Text features, such as Visual Basic.
With the exception of IPersistStream::GetSizeMax, IPersistStreamInit::GetSizeMax, and IPersistMemory::GetSizeMax, all methods of each interface must be fully implemented.