Edit

Share via

Property Set Serialization

  • Article

There are two versions of the property set serialization format. The original specification describes version 0 of the format. See Format Version for more information. Version 1 extends the original version. All version 0 property sets are valid as version 1 property sets. The Format Version field in the header of a serialized property set indicates the version.

The following items identify the differences between version 0 and version 1 property set serialization formats.

  • Support for new VARTYPE values. For more information about VARTYPE values and how to use them, see the topic IDispatch Data Types and Structures and the PROPVARIANT structure.

    The following VARTYPE values are not supported in version 0 property sets, but are supported in version 1:

    VT_I1

    VT_VECTOR | VT_I1

    VT_INT

    VT_UINT

    VT_DECIMAL

    Additionally, SafeArrays can be serialized in a property set. The presence of a SafeArray is indicated by the VT_ARRAY bit combined, using an OR operation, with the array elements in the vt member of the PROPVARIANT structure. For example, a SafeArray of 4-byte signed integers has a type of VT_ARRAY | VT_I4.

    The following element types are valid for a SafeArray in a serialized property set:

           
    VT_I1 VT_UI1 VT_I2 VT_UI2
    VT_I4 VT_UI4 VT_INT VT_UINT
    VT_R4 VT_R8 VT_CY VT_DATE
    VT_BSTR VT_BOOL VT_DECIMAL VT_ERROR
    VT_VARIANT      
         

    When the VT_VARIANT data type is specified, it indicates that the SafeArray itself holds PROPVARIANT structures. The types for these elements must be from the preceding list, except they cannot contain nested VT_VARIANT types.

    Note that implementations of IPropertyStorage must be able to recover gracefully by returning an error when a new type is encountered; for example, VARENUM types.

  • Case sensitive property names. Property names, for example those specified in the IPropertyStorage::WritePropertyNames method, are not case sensitive in version 0 property sets. In version 1 property sets, property names can be case-sensitive depending on the value of the new Behavior property.

    The Behavior property is Property ID 0x80000003 with a type of VT_UI4. If the lowest bit of this value is set, the property set names are case sensitive. Set the PROPSETFLAG_CASE_SENSITIVE flag in the grfFlags parameter of the IPropertySetStorage::Create method to specify a case-sensitive property set.

  • Long property names. Property names for version 0 property sets must be less than or equal to 256 characters, including the string terminator, for property sets in the Unicode code page. If not in the Unicode code page, they must be less than 256 bytes. Version 1 property sets, on the other hand, can have property names of unlimited length, although they are still limited by the overall property set size limit of 256 kilobytes (KB).

It is recommended that implementations of IPropertyStorage create and maintain version 0 property sets by default. If a caller subsequently requests a feature specific to the version 1 format, only then should the version of the property set be updated. For example, if a property of type VT_ARRAY is written or if a long property name is written, then the implementation should update the property set format to version 1. One exception to this guideline occurs if the PROPSETFLAG_CASE_SENSITIVE enumeration value is specified in the call to IPropertySetStorage::Create. In this case, the property set must be created as a version 1 property set.