Serializzazione set di proprietà

  • Articolo

Esistono due versioni del formato di serializzazione del set di proprietà. La specifica originale descrive la versione 0 del formato. Per altre informazioni, vedere Formato versione . La versione 1 estende la versione originale. Tutti i set di proprietà della versione 0 sono validi come set di proprietà della versione 1. Il campo Formato versione nell'intestazione di un set di proprietà serializzato indica la versione.

Gli elementi seguenti identificano le differenze tra i formati di serializzazione del set di proprietà versione 0 e versione 1.

  • Supporto per i nuovi valori VARTYPE . Per altre informazioni sui valori VARTYPE e su come usarli, vedere l'argomento IDispatch Data Type and Structures e la struttura PROPVARIANT .

    I valori VARTYPE seguenti non sono supportati nei set di proprietà versione 0, ma sono supportati nella versione 1:

    VT_I1

    VT_VECTOR | VT_I1

    VT_INT

    VT_UINT

    VT_DECIMAL

    Inoltre, SafeArrays può essere serializzato in un set di proprietà. La presenza di un oggetto SafeArray è indicata dal bit VT_ARRAY combinato, usando un'operazione OR , con gli elementi della matrice nel membro vt della struttura PROPVARIANT . Ad esempio, un valore SafeArray di interi con segno a 4 byte ha un tipo di VT_ARRAY | VT_I4.

    I tipi di elemento seguenti sono validi per un set di proprietà serializzato 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      
         

    Quando viene specificato il tipo di dati VT_VARIANT, indica che safeArray contiene strutture PROPVARIANT . I tipi per questi elementi devono trovarsi nell'elenco precedente, tranne che non possono contenere tipi di VT_VARIANT annidati.

    Si noti che le implementazioni di IPropertyStorage devono essere in grado di ripristinare in modo normale restituisce un errore quando viene rilevato un nuovo tipo; ad esempio, tipi VARENUM.

  • Nomi delle proprietà sensibili alle maiuscole e minuscole. I nomi delle proprietà, ad esempio quelli specificati nel metodo IPropertyStorage::WritePropertyNames , non fanno distinzione tra maiuscole e minuscole nei set di proprietà della versione 0. Nei set di proprietà versione 1 i nomi delle proprietà possono essere distinzione tra maiuscole e minuscole a seconda del valore della nuova proprietà Behavior.

    La proprietà Behavior è Id proprietà 0x80000003 con un tipo di VT_UI4. Se il bit più basso di questo valore è impostato, i nomi dei set di proprietà sono distinzione tra maiuscole e minuscole. Impostare il flag PROPSETFLAG_CASE_SENSITIVE nel parametro grfFlags del metodo IPropertySetStorage::Create per specificare un set di proprietà con distinzione tra maiuscole e minuscole.

  • Nomi di proprietà lunghi. I nomi delle proprietà per i set di proprietà della versione 0 devono essere inferiori o uguali a 256 caratteri, incluso il terminatore stringa, per i set di proprietà nella tabella codici Unicode. Se non nella tabella codici Unicode, devono essere inferiori a 256 byte. I set di proprietà versione 1, invece, possono avere nomi di proprietà di lunghezza illimitata, anche se sono ancora limitati dal limite complessivo delle dimensioni del set di proprietà pari a 256 kilobyte (KB).

È consigliabile che le implementazioni di IPropertyStorage creino e gestiscono i set di proprietà della versione 0 per impostazione predefinita. Se un chiamante richiede successivamente una funzionalità specifica per il formato versione 1, solo la versione del set di proprietà deve essere aggiornata. Ad esempio, se viene scritta una proprietà di tipo VT_ARRAY o se viene scritto un nome di proprietà lungo, l'implementazione deve aggiornare il formato impostato sulla versione 1. Un'eccezione a questa linea guida si verifica se il valore di enumerazione PROPSETFLAG_CASE_SENSITIVE viene specificato nella chiamata a IPropertySetStorage::Create. In questo caso, il set di proprietà deve essere creato come set di proprietà versione 1.