IEnumSTATPROPSTG

The IEnumSTATPROPSTG interface is used to iterate through an array of STATPROPSTG structures, which contain statistical information about an open property storage containing a property set. IEnumSTATPROPSTG has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

The implementation defines the order in which the properties in the set are enumerated. Properties that are present when the enumerator is created, and are not removed during the enumeration, will be enumerated only once. Properties added or deleted while the enumeration is in progress may or may not be enumerated, but they will never be enumerated more than once.

Properties with property ID 0 (dictionary), property ID 1 (codepage indicator), or property ID greater than or equal to 0x80000000 are not enumerated.

Enumeration of a non-simple property does not necessarily indicate that the property can be read successfully through a call to IPropertyStorage::ReadMultiple. This is because the performance overhead of checking existence of the indirect stream or storage is prohibitive during property enumeration. A client of this interface should code accordingly.

When to Implement

Implement IEnumSTATPROPSTG to enumerate the properties within a property set. If you are using the compound file implementation of the storage object, a pointer to which is available through a call to StgCreateDocfile, you can then query for a pointer to IPropertySetStorage. After calling one of its methods either to open or create a property set, you can get a pointer to IEnumSTATPROPSTG through a call to IPropertyStorage::Enum. If you are doing a custom implementation of IPropertyStorage, you also need to implement IEnumSTATPROPSTG to fill in a caller-allocated array of STATPROPSTG structures. Each STATPROPSTG structure contains information about a simple property.

When to Use

Applications that support storage objects and persistent properties within those objects call IPropertyStorage::Enum to return a pointer to IEnumSTATPROPSTG to enumerate the properties in the current property set.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG celt,           
  STATPROPSTG * rgelt,  
  ULONG * pceltFetched  
);
 
HRESULT Skip(
  ULONG celt  
);
 
HRESULT Reset(void)
 
HRESULT Clone(
  IEnumSTATPROPSTG ** ppenum  
);
 

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.

See Also

IPropertyStorage::Enum