Sérialisation de l’ensemble de propriétés

Il existe deux versions du format de sérialisation du jeu de propriétés. La spécification d’origine décrit la version 0 du format. Pour plus d’informations, consultez format de version. La version 1 étend la version d’origine. Tous les jeux de propriétés de version 0 sont valides en tant que jeux de propriétés version 1. Le champ version format dans l’en-tête d’un jeu de propriétés sérialisées indique la version.

Les éléments suivants identifient les différences entre les formats de sérialisation de la version 0 et de la version 1.

• Prise en charge des nouvelles valeurs VARTYPE. Pour plus d’informations sur valeurs VARTYPE et leur utilisation, consultez la rubrique types de données et structures IDispatch et la structure PROPVARIANT.

  Les valeurs de VARTYPE suivantes ne sont pas prises en charge dans les jeux de propriétés version 0, mais sont prises en charge dans la version 1 :

  VT_I1

  VT_VECTOR | VT_I1

  VT_INT

  VT_UINT

  VT_DECIMAL

  En outre, SafeArrays peut être sérialisé dans un jeu de propriétés. La présence d’un SafeArray est indiquée par le bit VT_ARRAY combiné, à l’aide d’une opération OR, avec les éléments de tableau dans le membre vt de la structure PROPVARIANT. Par exemple, un SafeArray d’entiers signés 4 octets a un type de VT_ARRAY | VT_I4.

  Les types d’éléments suivants sont valides pour un SafeArray dans un jeu de propriétés sérialisées :

  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

  Lorsque le type de données VT_VARIANT est spécifié, il indique que safeArray lui-même contient structures PROPVARIANT. Les types de ces éléments doivent provenir de la liste précédente, sauf qu’ils ne peuvent pas contenir de types VT_VARIANT imbriqués.

  Notez que les implémentations de IPropertyStorage doivent être en mesure de récupérer correctement en retournant une erreur lorsqu’un nouveau type est rencontré ; par exemple, les types VARENUM.

• Noms de propriétés sensibles à la casse. Les noms de propriétés, par exemple ceux spécifiés dans la méthode IPropertyStorage ::WritePropertyNames, ne respectent pas la casse dans les jeux de propriétés de version 0. Dans les jeux de propriétés de version 1, les noms de propriétés peuvent être sensibles à la casse en fonction de la valeur de la nouvelle propriété Behavior.

  La propriété Behavior est ID de propriété 0x80000003 avec un type de VT_UI4. Si le bit le plus bas de cette valeur est défini, les noms des ensembles de propriétés respectent la casse. Définissez l’indicateur PROPSETFLAG_CASE_SENSITIVE dans le paramètre grfFlags de la méthode IPropertySetStorage ::Create pour spécifier un jeu de propriétés respectant la casse.

• Noms de propriétés longs. Les noms de propriétés pour les jeux de propriétés de version 0 doivent être inférieurs ou égaux à 256 caractères, y compris la marque de fin de chaîne, pour les jeux de propriétés dans la page de codes Unicode. Si ce n’est pas dans la page de codes Unicode, elles doivent être inférieures à 256 octets. En revanche, les ensembles de propriétés de version 1 peuvent avoir des noms de propriétés de longueur illimitée, bien qu’ils soient toujours limités par la limite de taille globale du jeu de propriétés de 256 kilo-octets (Ko).

Il est recommandé que les implémentations de IPropertyStorage créer et gérer les ensembles de propriétés version 0 par défaut. Si un appelant demande par la suite une fonctionnalité spécifique au format version 1, seule la version du jeu de propriétés doit être mise à jour. Par exemple, si une propriété de type VT_ARRAY est écrite ou si un nom de propriété long est écrit, l’implémentation doit mettre à jour le format du jeu de propriétés sur la version 1. Une exception à cette directive se produit si la valeur d’énumération PROPSETFLAG_CASE_SENSITIVE est spécifiée dans l’appel à IPropertySetStorage ::Create. Dans ce cas, le jeu de propriétés doit être créé en tant que jeu de propriétés version 1.