PROPSETFLAG

The PROPSETFLAG enumeration values define characteristics of a property set. The values are used in the grfFlags parameter of IPropertySetStorage methods, the StgCreatePropStg function, and the StgOpenPropStg function.

typedef enum PROPSETFLAG {
    PROPSETFLAG_DEFAULT      = 0,
    PROPSETFLAG_NONSIMPLE    = 1,
    PROPSETFLAG_ANSI         = 2,
    PROPSETFLAG_UNBUFFERED   = 4
    } PROPSETFLAG
 

Elements

PROPSETFLAG_NONSIMPLE

If specified, storage-valued and stream-valued properties are permitted in the newly created set. Otherwise, they are not permitted. In the compound file and standalone implementations, property sets may be transacted only if PROPSETFLAG_NONSIMPLE is specified.

PROPSETFLAG_ANSI

If specified, all string values in the property set that are not explicitly Unicode (those other than VT_LPWSTR) are stored with the current system ANSI code page (see the Win32 function GetACP). Use of this value is not recommended, as described in the following Remarks section.

If this value is absent, string values in the new property set are stored in Unicode. The degree of control afforded by this value is necessary so clients using the property-related interfaces can interoperate well with standard property sets such as the OLE2 summary information, which may exist in the ANSI code page.

PROPSETFLAG_UNBUFFERED

Used only with the StgCreatePropStg and StgOpenPropStg functions, that is, in the standalone implementations of property set interfaces. If specified in these functions, changes to the property set are not buffered. Instead, changes are always written directly to the property set. A property set is changed by calls to its IPropertyStorage methods. However, by default, changes are buffered in an internal property set cache and are subsequently written to the property set when the IPropertyStorage::Commit method is called.

Setting PROPSETFLAG_UNBUFFERED reduces performance since the property set's internal buffer is automatically flushed after every change to the property set. However, writing changes directly prevents coordination problems. For example, suppose the storage object is opened in transacted mode, and the property set is buffered. Then, if you call the IStorage::Commit method on the storage object, the property set changes will not be picked up as part of the transaction, since they are in a buffer that has not been flushed yet. You must call IPropertyStorage::Commit prior to calling IStorage::Commit to flush the property set buffer before committing changes to the storage. As an alternative to making two calls, you can set PROPSETFLAG_UNBUFFERED so that changes are always written directly to the property set and are never buffered in the property set's internal cache. Then, the changes will be picked up when the transacted storage is committed.

Remarks

These values can be set and checked using bitwise operations that determine how property sets are created and opened. Property sets are created using the IPropertySetStorage::Create method or the StgCreatePropStg function. They are opened using the IPropertySetStorage::Open method or the StgOpenPropStg function.

It is recommended that property sets be created as Unicode, by not setting the PROPSETFLAG_ANSI flag in the grfFlags parameter. It is also recommended that you avoid using VT_LPSTR values, and use VT_LPWSTR values instead. When the property set code page is Unicode, VT_LPSTR string values are converted to Unicode when stored, and converted back to multibyte string values when retrieved. When the code page of the property set is not Unicode, property names, VT_BSTR strings, and non-simple property values are converted to multibyte strings when stored, and converted back to Unicode when retrieved, all using the current system ANSI code page.

Programming Information

QuickInfo

  Windows NT: Use version 3.1 and later.
  Windows: Use Windows 95 and later. Requires DCOM95.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.

See Also

FmtIdToPropStgName, IPropertySetStorage::Create, IPropertySetStorage::Open, PropStgNameToFmtId, StgCreatePropSetStg, StgCreatePropStg, StgOpenPropStg