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 Format Version 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 Format Version no cabeçalho de um conjunto de propriedades serializadas 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 de VARTYPE. Para obter mais informações sobre valores de VARTYPE e como usá-los, consulte o tópico IDispatch Data Types and Structures e a estruturaPROPVARIANT.

  Os seguintes valores VARTYPE não são suportados nos conjuntos de propriedades da versão 0, mas são suportados na versão 1:

  VT_I1

  VT_VETOR | 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 da matriz no vt membro da estruturaPROPVARIANT. Por exemplo, um SafeArray de inteiros assinados 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 serializadas:

  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, isso indica que o próprio SafeArray mantém estruturas de PROPVARIANT. Os tipos para esses elementos devem ser da lista anterior, exceto que eles não podem conter tipos de VT_VARIANT aninhados.

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

• Nomes de propriedades que diferenciam maiúsculas de minúscula 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 de propriedade 0x80000003 com um tipo de VT_UI4. Se o bit mais baixo desse valor for definido, os nomes dos conjuntos de propriedades diferenciarão 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 propriedades 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 devem 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 estejam limitados pelo limite de tamanho geral do conjunto de propriedades de 256 kilobytes (KB).

É recomendável que implementações de IPropertyStorage criar e manter 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 deve ser atualizada. Por exemplo, se uma propriedade do tipo VT_ARRAY for gravada ou se um nome de propriedade longo for gravado, a implementação deverá atualizar o formato do conjunto de propriedades para a versão 1. Uma exceção a essa diretriz ocorre 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 versão 1.