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 the Component Categories section of this appendix.
|
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[Init]::GetSizeMax and IPersistMemory::GetSizeMax,
all methods of each interface must be fully implemented.