IPropertySetStorage-Compound File Implementation
The COM compound file storage object implementation includes an implementation of both IPropertyStorage, the interface that manages a single persistent property set, and IPropertySetStorage, the interface that manages groups of persistent property sets.
To get a pointer to the compound file implementation of IPropertySetStorage, specify the header-defined name for the identifier IID_IStorage as the riid parameter, or use the StgCreateStorageEx or StgOpenStorageEx functions. In both cases, specify STGFMT_STORAGE as the stgfmt parameter. (STGFMT_ANY can alternatively be specified in the case of StgOpenStorageEx.) Also, specify the header-defined name for the interface identifier (IID) IID_IPropertySetStorage as the riid parameter. Both functions supply a pointer to the object IPropertySetStorage interface.
Another way to get a pointer to the compound file implementation is to specify the header-defined name for the identifier IID_IStorage as the riid parameter, or to use the StgCreateDocfile or StgOpenStorage functions. This will supply a pointer to the object IStorage interface. When you want to deal with persistent property sets, call IStorage::QueryInterface for the IPropertySetStorage interface.
When to Use IPropertySetStorage
Call the methods of IPropertySetStorage to create, open, or delete property sets in the current compound-file property set storage. There is also a method, IPropertySetStorage::Enum, that supplies a pointer to an enumerator that can be used to enumerate the property sets in the storage.
Methods
Creates a new property set in the current compound file storage and, on return, supplies an interface pointer to the IPropertyStorage compound-file implementation. In this implementation, property sets may be transacted only if PROPSETFLAG_NONSIMPLE is specified. This method requires that the sharing mode specified in the grfMode parameter be STGM_SHARE_EXCLUSIVE, and that the access mode be either STGM_READ or STGM_READWRITE (STGM_WRITE mode is not supported).
Opens an existing property set in the current property storage. On return, it supplies an interface pointer to the compound file implementation of IPropertyStorage. This method requires that the sharing mode specified in the grfMode parameter be STGM_SHARE_EXCLUSIVE, and that the access mode be either STGM_READ or STGM_READWRITE (STGM_WRITE is not supported).
Deletes a property set in this property storage.
Creates an object used to enumerate STATPROPSETSTG structures. Each STATPROPSETSTG structure provides data about a single property set.
Remarks
Starting with Windows 2000, the compound-file implementation of IPropertySetStorage supports simple mode. Simple mode is indicated by specifying the STGM_SIMPLE flag for the StgCreateStorageEx and StgOpenStorageEx functions. If the compound file is opened in simple mode, the associated IPropertySetStorage implementation is limited as follows:
- Only simple property sets can be created. That is, specifying the PROPSETFLAG_NONSIMPLE value in the grfFlags parameter for the IPropertySetStorage::Create method results in an error.
- After you create a compound file with StgCreateStorageEx using STGM_SIMPLE and query for the IPropertySetStorage interface, you can only call IPropertySetStorage::Create once. Then you must release the IPropertyStorage interface before calling the Create method again. For more information about simple mode, see STGM Constants.
- You cannot use the IPropertySetStorage::Open method to open a property set after using StgCreateStorageEx to create the storage object. Instead you must use StgOpenStorageEx before querying for IPropertySetStorage and calling the Open method.
- After you open a compound file with StgOpenStorageEx using the STGM_SIMPLE flag and query for the IPropertySetStorage interface, you can open one property set at a time using IPropertySetStorage::Open. Also, it may not be possible for the total size of the property set to be increased while the property set is open.
Simple property sets cannot be transacted. You cannot specify STGM_TRANSACTED in the grfmode parameter of the Create and Open methods unless you also specify PROPSETFLAG_NONSIMPLE in the grfFlags parameter. Be aware that simple and non-simple property sets are unrelated to the simple-mode property sets described above. For more information about simple and nonsimple property sets, see Storage and Stream Objects for a Property Set.
Note
The DocumentSummaryInformation and UserDefined property sets are unique in that they may have two property set sections. For more information, see The DocumentSummaryInformation and UserDefined Property Sets.
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for