ISyncKnowledge2::SerializeWithOptions

  • Artigo

Serializa os dados do objeto de conhecimento para uma matriz de bytes com base nas opções de versão e serialização especificadas.

HRESULT SerializeWithOptions(
  SYNC_SERIALIZATION_VERSION targetFormatVersion,
  DWORD dwFlags,
  BYTE* pBuffer,
  DWORD* pdwSerializedSize);

Parâmetros

Termo

Definição

targetFormatVersion

[in] O conhecimento serializado é compatível com essa versão.

dwFlags

[in] As opções que especificam informações adicionais sobre como serializar o objeto. Deve ser 0 ou uma combinação dos valores que são especificados pelos sinalizadores SYNC_SERIALIZE. Quando 0 for especificado, o mapa de chave de réplica não será incluído como parte dos dados de conhecimento serializados.

pBuffer

[in, out, unique, size_is(*pdwSerializedSize)] Os dados serializados do objeto de conhecimento são serializados para esse buffer.

pdwSerializedSize

[in, out] Especifica o número de bytes em pBuffer. Retorna o número de bytes necessários para serializar os dados de conhecimento quando pBuffer for muito pequeno ou retorna o número de bytes gravados.

Valor de retorno

  • S_OK.

  • E_POINTER.

  • HRESULT_FROM_WIN32(ERROR_MORE_DATA) quando pBuffer for muito pequeno. Nessa situação, o número de bytes necessários é retornado em pdwSerializedSize.

  • SYNC_E_INVALID_VERSION quando o valor de targetFormatVersion for maior do que a versão do objeto ou quando o objeto contiver elementos não compatíveis com targetFormatVersion.

Comentários

O valor de targetFormatVersion determina o formato dos dados de conhecimento serializados. Quando SYNC_SERIALIZATION_VERSION_V1 é especificado, o formato serializado é compatível com os componentes do Sync Framework 1.0 e posterior. Quando SYNC_SERIALIZATION_VERSION_V2 é especificado, o formato serializado é compatível com os componentes do Sync Framework 2.0. Se SYNC_SERIALIZATION_VERSION_V2 for especificado quando o objeto de conhecimento contiver elementos não compatíveis com o Sync Framework 1.0, SYNC_E_INVALID_VERSION será retornado. Por exemplo, o conhecimento que é retornado por ISyncKnowledge2::ProjectOntoColumnSet contém elementos que foram introduzidos no Sync Framework 2.0 e, portanto, não podem ser serializados com SYNC_SERIALIZATION_VERSION_V1 especificado para targetFormatVersion.

Dica

A serialização para o formato do Sync Framework 1.0 é menos eficiente do que para o formato do Sync Framework 2.0. A menos que haja uma necessidade específica do formato do Sync Framework 1.0, o formato do Sync Framework 2.0 deve ser usado.

O objeto Interface IReplicaKeyMap correto é necessário para desserializar um objeto de conhecimento usando IProviderSyncServices::DeserializeSyncKnowledge. Quando SYNC_SERIALIZE_REPLICA_KEY_MAP é especificado para flags, o objeto IReplicaKeyMap é serializado com os dados de conhecimento. Quando esse sinalizador não é especificado, os dados de IReplicaKeyMap devem ser armazenados de algum outro modo para que o objeto de conhecimento possa ser desserializado.

Formato de serialização

O conhecimento serializado contido em pBuffer é armazenado de forma compacta, sem preenchimento, em ordem de byte big endian.

Quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V1, o conhecimento será serializado de acordo com o formato descrito em ISyncKnowledge::Serialize. Do contrário, o conhecimento serializado conterá os elementos abaixo, na ordem a seguir.

  1. Uma seção de cabeçalho. A seção de cabeçalho contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A versão do formato de serialização. É o valor contido em targetFormatVersion e deve ser um valor válido da enumeração SYNC_SERIALIZATION_VERSION.

    ULONG

    4

    Reservado. Esse valor é sempre 0.

    ULONG

    4

    A versão mínima com suporte do conhecimento serializado.

    ULONG

    4

    Reservado. Esse valor é sempre 0.

  2. Uma seção do mapa de chave de réplica quando dwFlags contiver SYNC_SERIALIZE_REPLICA_KEY_MAP. Caso contrário, não haverá uma seção do mapa de chave de réplica. O formato da seção do mapa de chave de réplica é definido em IReplicaKeyMap::Serialize.

  3. Uma assinatura que indica o próximo conjunto de seções:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A assinatura da seção. Esse valor é sempre 24.

  4. Uma seção do esquema do formato da ID. A seção do esquema do formato da ID contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    BOOL

    1

    Indica se as IDs de réplica contidas no conhecimento têm comprimento fixo ou variável. Esse valor será 0 se as IDs tiverem comprimento fixo; ou 1 se tiverem comprimento variável.

    USHORT

    2

    O comprimento, em bytes, das IDs de réplica de comprimento fixo, ou o comprimento máximo das IDs de comprimento variável.

    BOOL

    1

    Indica se as IDs de item contidas no conhecimento têm comprimento fixo ou variável. Esse valor será 0 se as IDs tiverem comprimento fixo; ou 1 se tiverem comprimento variável.

    USHORT

    2

    O comprimento, em bytes, das IDs de item de comprimento fixo, ou o comprimento máximo das IDs de comprimento variável.

    BOOL

    1

    Indica se as IDs de unidade de alteração contidas no conhecimento têm comprimento fixo ou variável. Esse valor será 0 se as IDs tiverem comprimento fixo; ou 1 se tiverem comprimento variável.

    USHORT

    2

    O comprimento, em bytes, das IDs de unidade de alteração de comprimento fixo, ou o comprimento máximo das IDs de comprimento variável.

  5. Uma seção da tabela do vetor de relógio. A seção da tabela do vetor de relógio contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A assinatura da tabela do vetor de relógio. Esse valor é sempre 21.

    ULONG

    4

    O número de vetores de relógio contidos na tabela de vetores de relógio.

  6. A tabela de vetores de relógio contém uma lista de vetores de relógio, com o número de vetores de relógio igual ao valor especificado no ULONG anterior. Cada vetor de relógio contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A assinatura do vetor de relógio. Esse valor é 1 quando o vetor de relógio não contém itens de feed do FeedSync; caso contrário, o valor é 9 quando o vetor de relógio contém itens de feed do FeedSync.

    ULONG

    4

    O número de elementos de vetor de relógio contidos nesse vetor de relógio.

    Quando o vetor de relógio contém itens de feed do FeedSync, a seção a seguir está presente no conhecimento serializado; caso contrário, ela não existe:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    O número de atualizações feitas no feed do FeedSync associado a esse conhecimento. Esse valor corresponde ao atributo updates do feed do FeedSync.

    BYTE

    1

    Indica se o feed do FeedSync controla conflitos. Esse valor corresponde ao atributo noconflicts do feed do FeedSync. Esse valor é 0 quando noconflicts não está definido; caso contrário, o valor é 1.

    O restante do vetor de relógio contém uma lista dos elementos de vetor de relógio, com o número de elementos igual ao valor previamente especificado na seção de vetor de relógio.

    Cada elemento de vetor de relógio contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A chave de uma réplica.

    ULONGLONG

    8

    Uma contagem em escala.

    Quando o conhecimento é associado a um feed do FeedSync, cada elemento de vetor de relógio contém os seguintes elementos adicionais:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A parte da data do valor when do feed do FeedSync.

    ULONG

    4

    A parte da hora do valor when do feed do FeedSync.

    BYTE

    1

    Os sinalizadores associados ao feed do FeedSync.

  7. Uma seção do conjunto de intervalos. Essa seção contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A assinatura da seção do conjunto de intervalos. Esse valor é sempre 23.

    ULONG

    4

    O número de conjuntos de intervalos inclusos nessa seção.

    A seção do conjunto de intervalos contém uma lista de conjuntos de intervalos, com o número de conjuntos de intervalos igual ao valor especificado no ULONG anterior. O primeiro conjunto de intervalos é o conjunto de intervalos do escopo.

    Cada conjunto de intervalos contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A assinatura do conjunto de intervalos. Esse valor é sempre 22.

    ULONG

    4

    O número de intervalos inclusos nesse conjunto de intervalos.

    Cada intervalo do conjunto contém os elementos a seguir:

    Quando as IDs de item têm comprimento fixo:

    Tipo de dados Comprimento em bytes Descrição

    Sequência de bytes

    O comprimento especificado no formato de ID de item.

    A ID de item de comprimento fixo que inicia o intervalo.

    Ou quando as IDs de item têm comprimento variável:

    Tipo de dados Comprimento em bytes Descrição

    USHORT

    2

    O comprimento, em bytes, da ID de comprimento variável. Esse comprimento inclui os dois bytes para o USHORT que contém o comprimento, mais os bytes que contêm a ID real.

    Sequência de bytes

    O comprimento especificado no USHORT anterior.

    A ID de item de comprimento variável que inicia o intervalo.

    Cada intervalo contém o elemento adicional a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    Um índice na tabela de vetores de relógio contido nesses dados serializados.

  8. Uma seção do conjunto de colunas. Essa seção contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    O número de colunas inclusas nessa seção.

    Cada coluna na seção do conjunto de colunas contém os elementos a seguir:

    Quando as IDs de unidade de alteração têm comprimento fixo:

    Tipo de dados Comprimento em bytes Descrição

    Sequência de bytes

    O comprimento especificado no formato da ID de unidade de alteração.

    A ID da unidade de alteração de comprimento fixo.

    Ou, quando as IDs de unidade de alteração têm comprimento variável:

    Tipo de dados Comprimento em bytes Descrição

    USHORT

    2

    O comprimento, em bytes, da ID de comprimento variável. Esse comprimento inclui os dois bytes para o USHORT que contém o comprimento, mais os bytes que contêm a ID real.

    Sequência de bytes

    O comprimento especificado no USHORT anterior.

    A ID da unidade de alteração de comprimento variável.

    Cada coluna na seção do conjunto de colunas contém o elemento adicional a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    Um índice na seção do conjunto de intervalos contido nesses dados serializados.

  9. Quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V3 ou superior, os dados serializados conterão uma seção do conjunto de marcadores. Essa seção contém os elementos a seguir:

    Tipo de dados Comprimento em bytes Descrição

    ULONG

    4

    A assinatura da seção do conjunto de marcadores. Esse valor é sempre 25.

    BOOL

    1

    Indica se os itens listados nessa seção contêm todas as unidades de alteração ou exigem todas as unidades de alteração. Esse valor é 0 quando unidades de alteração estão presentes, ou 1 quando unidades de alteração são necessárias. Apenas um desses tipos de marcador pode estar presente.

    ULONG

    4

    O número de IDs de itens listadas nessa seção.

    A seção do conjunto de marcadores contém uma lista de IDs de item, com o número de IDs igual ao valor contido no ULONG anterior.

    Cada ID de item contém os elementos a seguir:

    Quando as IDs de item têm comprimento fixo:

    Tipo de dados Comprimento em bytes Descrição

    Sequência de bytes

    O comprimento especificado no formato de ID de item.

    A ID de item de comprimento fixo.

    Ou quando as IDs de item têm comprimento variável:

    Tipo de dados Comprimento em bytes Descrição

    USHORT

    2

    O comprimento, em bytes, da ID de comprimento variável. Esse comprimento inclui os dois bytes para o USHORT que contém o comprimento, mais os bytes que contêm a ID real.

    Sequência de bytes

    O comprimento especificado no USHORT anterior.

    A ID de item de comprimento variável.

Consulte também

Referência

Interface ISyncKnowledge2