Serializzazione set di proprietà

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.