IPropertySetStorage-Standalone Implementation

The system-provided, standalone implementation of IPropertySetStorage includes an implementation of both IPropertyStorage, the interface that reads and writes properties in a property set storage, and IPropertySetStorage, the interface that creates and opens property sets in a storage. The IEnumSTATPROPSTG and IEnumSTATPROPSETSTG interfaces are also provided in the standalone implementation.

To use the standalone implementation of IPropertySetStorage, you first obtain a pointer to the system-provided, standalone implementation and associate the system-provided implementation with your storage object. To get a pointer to the standalone implementation of IPropertySetStorage, call the StgCreatePropSetStg function and provide the pStorage parameter specifying the storage object that will contain the property set. This function supplies you with a pointer to the new IPropertySetStorage interface for the specified storage object.

The standalone implementation of IPropertySetStorage creates property sets on any storage or stream object, not just on compound file storages and streams. The standalone implementation does not depend on compound files and can be used with any implementation of structured storages. See the section IPropertySetStorage-Compound File Implementation in the Object Services section of the Platform SDK for more information on the compound file implementation of this interface.

When to Use

Call the methods of IPropertySetStorage to create, open, and delete property sets in any structured storage. There is also a method that supplies a pointer to the IEnumSTATPROPSETSTG enumerator that can be used to enumerate the property sets in the storage.

The standalone implementation also provides the StgCreatePropStg and the StgOpenPropStg helper functions in addition to the Create and Open methods to create and open property sets. These two functions add support for the PROPSETFLAG_UNBUFFERED value so you can directly write changes to the property set instead of buffering them in a cache. See the PROPSETFLAG enumeration for more information on using this value.

Remarks

The standalone implementation of IPropertySetStorage supports the following methods:

IPropertySetStorage::Create

Creates a new property set in the storage and returns a pointer to the IPropertyStorage interface on the property set.

If you plan to use the PROPSETFLAG_UNBUFFERED value, use the StgCreatePropStg function instead to create and open the new property set and to obtain a pointer to the standalone implementation for the IPropertyStorage interface on the property set.

IPropertySetStorage::Open

Opens an existing property set in the storage and returns a pointer to the IPropertyStorage interface on the property set.

If you plan to use the PROPSETFLAG_UNBUFFERED value, use the StgOpenPropStg function instead to obtain a pointer to the standalone implementation of IPropertyStorage on the specified property set.

IPropertySetStorage::Delete

Deletes a property set in this property set storage.

IPropertySetStorage::Enum

Creates an object that can be used to enumerate STATPROPSETSTG structures. Each STATPROPSETSTG structure provides information about a single property set.

Note  The DocumentSummaryInformation property set is special, in that it may have two property set sections. This property set is described in the Object Services topic of the Platform SDK in the section titled "The DocumentSummaryInformation Property Set." The second property set is referred to as the User-Defined Properties. Each section is identified with a unique Format ID, for example FMTID_DocumentSummaryInformation and FMTID_UserDefinedProperties.

When IPropertySetStorage::Create is called to create the User-Defined Property Set, the first section is created automatically. Thus once FMTID_UserDefinedProperties is created, FMTID_DocumentSummaryInformation need not be created, but can be opened with a call to IPropertySetStorage::Open. Note that creating the first section does not automatically create the second section. It is not possible to open both sections simultaneously.

Alternately, when IPropertySetStorage::Delete is called to delete the first section, both sections are deleted. That is, calling IPropertySetStorage::Delete with FMTID_DocumentSummaryInformation, causes both that section and the FMTID_UserDefinedProperties section to be deleted. Note that deleting the second section does not automatically delete the first section.

Finally, when IPropertySetStorage::Enum is used to enumerate property sets, the User-Defined Property Set isl not enumerated.

Programming Information

See Also

IPropertyStorage, IPropertySetStorage - Compound File Implementation, IPropertyStorage-Standalone Implementation, STATPROPSETSTG, PROPSETFLAG, IStorage::EnumElements, STGM, StgCreatePropStg, StgOpenPropStg, StgCreatePropSetStg