Serialização do conjunto de propriedades

Há duas versões do formato de serialização do conjunto de propriedades. A especificação original descreve a versão 0 do formato. Consulte Formatar Versão para obter mais informações. A versão 1 estende a versão original. Todos os conjuntos de propriedades da versão 0 são válidos como conjuntos de propriedades da versão 1. O campo Formatar Versão no cabeçalho de um conjunto de propriedades serializado indica a versão.

Os itens a seguir identificam as diferenças entre os formatos de serialização do conjunto de propriedades versão 0 e versão 1.

• Suporte para novos valores VARTYPE . Para obter mais informações sobre valores VARTYPE e como usá-los, consulte o tópico Tipos e estruturas de dados IDispatch e a estrutura PROPVARIANT .

  Os seguintes valores VARTYPE não têm suporte em conjuntos de propriedades da versão 0, mas têm suporte na versão 1:

  VT_I1

  VT_VECTOR | VT_I1

  VT_INT

  VT_UINT

  VT_DECIMAL

  Além disso, SafeArrays pode ser serializado em um conjunto de propriedades. A presença de um SafeArray é indicada pelo VT_ARRAY bit combinado, usando uma operação OR , com os elementos de matriz no membro vt da estrutura PROPVARIANT . Por exemplo, um SafeArray de inteiros com sinal de 4 bytes tem um tipo de VT_ARRAY | VT_I4.

  Os seguintes tipos de elemento são válidos para um SafeArray em um conjunto de propriedades serializado:

  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 o tipo de dados VT_VARIANT é especificado, ele indica que a própria SafeArray contém estruturas PROPVARIANT . Os tipos desses elementos devem ser da lista anterior, exceto que não podem conter tipos de VT_VARIANT aninhados.

  Observe que as implementações de IPropertyStorage devem ser capazes de se recuperar normalmente retornando um erro quando um novo tipo é encontrado; por exemplo, tipos VARENUM.

• Nomes de propriedade que diferenciam maiúsculas de minúsculas. Os nomes de propriedade, por exemplo, aqueles especificados no método IPropertyStorage::WritePropertyNames , não diferenciam maiúsculas de minúsculas nos conjuntos de propriedades da versão 0. Nos conjuntos de propriedades da versão 1, os nomes de propriedade podem diferenciar maiúsculas de minúsculas, dependendo do valor da nova propriedade Behavior.

  A propriedade Behavior é ID da propriedade 0x80000003 com um tipo de VT_UI4. Se o bit mais baixo desse valor for definido, os nomes do conjunto de propriedades diferenciam maiúsculas de minúsculas. Defina o sinalizador PROPSETFLAG_CASE_SENSITIVE no parâmetro grfFlags do método IPropertySetStorage::Create para especificar um conjunto de propriedades que diferencia maiúsculas de minúsculas.

• Nomes de propriedade longos. Os nomes de propriedade para conjuntos de propriedades da versão 0 devem ser menores ou iguais a 256 caracteres, incluindo o terminador de cadeia de caracteres, para conjuntos de propriedades na página de código Unicode. Se não estiver na página de código Unicode, eles deverão ter menos de 256 bytes. Os conjuntos de propriedades da versão 1, por outro lado, podem ter nomes de propriedade de comprimento ilimitado, embora ainda sejam limitados pelo limite geral de tamanho do conjunto de propriedades de 256 quilobytes (KB).

É recomendável que as implementações de IPropertyStorage criem e mantenham conjuntos de propriedades da versão 0 por padrão. Se um chamador solicitar posteriormente um recurso específico para o formato da versão 1, somente então a versão do conjunto de propriedades será atualizada. Por exemplo, se uma propriedade do tipo VT_ARRAY for gravada ou se um nome de propriedade longa for gravado, a implementação deverá atualizar o formato do conjunto de propriedades para a versão 1. Uma exceção a essa diretriz ocorrerá se o valor de enumeração PROPSETFLAG_CASE_SENSITIVE for especificado na chamada para IPropertySetStorage::Create. Nesse caso, o conjunto de propriedades deve ser criado como um conjunto de propriedades da versão 1.