Sérialisation du jeu de propriétés

  • Article

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 version . La version 1 étend la version d’origine. Tous les jeux de propriétés de la version 0 sont valides en tant que jeux de propriétés de la version 1. Le champ Format de version 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 des jeux de propriétés version 0 et version 1.

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

    Les valeurs 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 VT_ARRAY bit 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 de 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 le SafeArray lui-même contient des 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 d’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 respectant 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 version 0. Dans les jeux de propriétés de la version 1, les noms de propriétés peuvent respecter la casse en fonction de la valeur de la nouvelle propriété Behavior.

    La propriété Behavior est l’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 des jeux de propriétés 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. S’ils ne sont pas dans la page de codes Unicode, ils doivent être inférieurs à 256 octets. En revanche, les jeux de propriétés version 1 peuvent avoir des noms de propriétés d’une 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 d’IPropertyStorage créent et gèrent des jeux de propriétés version 0 par défaut. Si un appelant demande par la suite une fonctionnalité spécifique au format version 1, c’est seulement alors que 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 de jeu de propriétés vers 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.