プロパティ セットのシリアル化

プロパティ セットのシリアル化形式には 2 つのバージョンがあります。 元の仕様では、形式のバージョン 0 が記述されています。 詳細については、「 バージョンの書式設定 」を参照してください。 バージョン 1 は、元のバージョンを拡張します。 バージョン 0 のすべてのプロパティ セットは、バージョン 1 のプロパティ セットとして有効です。 シリアル化されたプロパティ セットのヘッダーの [バージョンの書式設定 ] フィールドは、バージョンを示します。

次の項目は、バージョン 0 とバージョン 1 のプロパティ セットのシリアル化形式の違いを示しています。

• 新しい VARTYPE 値のサポート。 VARTYPE 値とその使用方法の詳細については、トピック「IDispatch Data Types and Structures and the PROPVARIANT structure」を参照してください。

  次の VARTYPE 値は、バージョン 0 のプロパティ セットではサポートされていませんが、バージョン 1 ではサポートされています。

  VT_I1

  VT_VECTOR |VT_I1

  VT_INT

  VT_UINT

  VT_DECIMAL

  さらに、SafeArrays はプロパティ セットでシリアル化できます。 SafeArray の存在は、VT_ARRAY ビットを組み合わせて、OR 演算を使用して、PROPVARIANT 構造体の vt メンバー内の配列要素と共に示されます。 たとえば、4 バイト符号付き整数の SafeArray には、VT_ARRAY |VT_I4。

  次の要素型は、シリアル化されたプロパティ セット内の SafeArray に対して有効です。

  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

  VT_VARIANTデータ型を指定すると、SafeArray 自体が PROPVARIANT 構造体を保持していることを示します。 これらの要素の型は、入れ子になったVT_VARIANT型を含めることはできませんが、前のリストの型である必要があります。

  IPropertyStorage の実装は、新しい型が検出されたときにエラーを返すことによって正常に回復できる必要があることに注意してください。たとえば、VARENUM 型です。

• 大文字と小文字を区別するプロパティ名。 プロパティ名 ( IPropertyStorage::WritePropertyNames メソッドで指定されたものなど) は、バージョン 0 のプロパティ セットでは大文字と小文字は区別されません。 バージョン 1 のプロパティ セットでは、プロパティ名は、新しい Behavior プロパティの値に応じて大文字と小文字を区別できます。

  Behavior プロパティは、VT_UI4の種類を持つ プロパティ ID 0x80000003です。 この値の最小ビットが設定されている場合、プロパティ セット名では大文字と小文字が区別されます。 大文字と小文字を区別するプロパティ セットを指定するには、IPropertySetStorage::Create メソッドの grfFlags パラメーターに PROPSETFLAG_CASE_SENSITIVE フラグを設定します。

• 長いプロパティ名。 バージョン 0 のプロパティ セットのプロパティ名は、Unicode コード ページのプロパティ セットの場合、文字列ターミネータを含めて 256 文字以下である必要があります。 Unicode コード ページにない場合は、256 バイト未満にする必要があります。 一方、バージョン 1 のプロパティ セットは、プロパティ名の長さが無制限に設定できますが、プロパティ セットのサイズ制限全体は 256 KB (KB) に制限されます。

IPropertyStorage の実装では、既定でバージョン 0 のプロパティ セットを作成および管理することをお勧めします。 呼び出し元が後でバージョン 1 形式に固有の機能を要求した場合にのみ、プロパティ セットのバージョンを更新する必要があります。 たとえば、VT_ARRAY型のプロパティが書き込まれる場合、または長いプロパティ名が書き込まれている場合、実装ではプロパティ セットの形式をバージョン 1 に更新する必要があります。 このガイドラインの 1 つの例外は、 IPropertySetStorage::Create の呼び出しでPROPSETFLAG_CASE_SENSITIVE列挙値が指定されている場合に発生します。 この場合、プロパティ セットはバージョン 1 のプロパティ セットとして作成する必要があります。