ISyncChangeBatchBase2::SerializeWithOptions
Serializa os dados do objeto de lote de alterações 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 * pbBuffer,
DWORD * pdwSerializedSize);
Parâmetros
Termo |
Definição |
targetFormatVersion |
[in] O lote de alterações serializado é compatível com esta versão. |
dwFlags |
[in] Reservado. Deve ser 0. |
pbBuffer |
[in, out, unique, size_is(*pdwSerializedSize)] Os dados serializados do objeto de lote de alterações 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 do lote de alterações quando pBuffer for muito pequeno, ou retorna o número de bytes gravados. |
Valor de retorno
S_OK.
E_INVALIDARG quando dwFlags não é 0, ou quando a versão especificada por targetFormatVersion for incompatível com os dados do objeto de lote de alterações.
E_OUTOFMEMORY.
E_POINTER.
HRESULT_FROM_WIN32(ERROR_MORE_DATA) quando pBuffer for muito pequeno. Nessa situação, o número de bytes necessário é retornado em pdwSerializedSize.
SYNC_E_INVALID_OPERATION quando o lote de alterações contiver um grupo que foi iniciado mas não foi encerrado.
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 do lote de alterações serializado. 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 lote de alterações contiver elementos não compatíveis com o Sync Framework 1.0, E_INVALIDARG ou SYNC_E_INVALID_OPERATION será retornado.
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.
Formato de serialização
O lote de alterações serializado contido em pbBuffer é armazenado em forma compacta, sem preenchimento, em ordem de byte big-endian. O lote de alterações serializado contém os elementos abaixo, na ordem a seguir.
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 ULONGLONG
8
A versão do formato de serialização do lote de alterações. Esse valor será 3 quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V1, será 4 quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V2 e será 5 quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V3.
Uma seção de informações de filtro quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V2, e as informações de filtro estiverem presentes no lote de alterações. A seção de informações de filtro contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, da seção de informações de filtro.
O resto da seção de informações de filtro está no formato descrito em ISyncFilterInfo::Serialize.
Uma seção de conhecimento de destino. A seção de conhecimento de destino contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, da seção de conhecimento de destino. Esse comprimento pode ser 0 e, nesse caso, não haverá nenhum conhecimento de destino a seguir.
Sequência de bytes
O comprimento especificado no ULONG anterior.
Quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V1, o conhecimento de destino estará no formato descrito por ISyncKnowledge::Serialize. Caso contrário, o conhecimento de destino estará no formato descrito por ISyncKnowledge2::SerializeWithOptions. O conhecimento de destino serializado sempre contém o mapa de chave da réplica serializada.
Uma seção de conhecimento esquecido de origem. Essa seção contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, da seção de conhecimento esquecido de origem. Esse comprimento pode ser 0 e, nesse caso, não haverá nenhum conhecimento esquecido de origem a seguir.
Sequência de bytes
O comprimento especificado no ULONG anterior.
Quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V1, o conhecimento esquecido de origem estará no formato descrito por ISyncKnowledge::Serialize. Caso contrário, o conhecimento esquecido de origem estará no formato descrito por ISyncKnowledge2::SerializeWithOptions. O conhecimento esquecido de origem serializado sempre contém o mapa de chave da réplica serializada.
Uma seção de mapa de chave de filtro de origem, quando targetFormatVersion é SYNC_SERIALIZATION_VERSION_V3 e as informações de mapa de chave de filtro de origem estão presentes. A seção de mapa de chave de filtro de origem contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, da seção de mapa de chave de filtro de origem. O comprimento pode ser 0 e, nesse caso, nenhum mapa de chave de filtro de origem segue.
USHORT
2
A versão do formato de serialização do mapa de chave de filtro. Esse valor é SYNC_SERIALIZATION_VERSION_V3.
ULONG
4
O número de filtros no mapa de chave de filtro.
Cada filtro no mapa de chave de filtro contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, do filtro.
Sequência de bytes
O comprimento especificado no ULONG anterior.
Os dados do filtro serializados gravados no fluxo pelo método ISyncFilter::Serialize.
Uma seção de conhecimento atual. Essa seção contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O número de objetos de conhecimento atual contidos nos dados serializados. Esse número pode ser 0 e, nesse caso, não haverá nenhum conhecimento atual a seguir.
Cada conhecimento atual contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, do conhecimento atual.
Sequência de bytes
O comprimento especificado no ULONG anterior.
Quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V1, o conhecimento atual estará no formato descrito por ISyncKnowledge::Serialize. Caso contrário, o conhecimento atual estará no formato descrito por ISyncKnowledge2::SerializeWithOptions. O conhecimento atual serializado sempre contém o mapa de chave da réplica serializada.
Uma seção de conjunto de alterações. Essa seção contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O número de objetos de alteração contidos nos dados serializados. Esse número pode ser 0 e, nesse caso, não haverá nenhuma alteração a seguir.
Cada alteração contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, dos dados de alteração.
ULONGLONG
8
A assinatura do formato de serialização do objeto de alteração. Esse valor será 5 quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V1 ou SYNC_SERIALIZATION_VERSION_V2, e será 6 quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V3.
Quando as IDs de réplica têm comprimento fixo.
Tipo de dados Comprimento em bytes Descrição Sequência de bytes
O comprimento especificado no formato de ID da réplica.
A ID de réplica de comprimento fixo.
Ou, quando as IDs de réplica tiverem 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 réplica de comprimento variável.
Cada alteração contém os elementos adicionais a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
A chave de réplica que identifica qual réplica fez essa alteração.
ULONGLONG
8
A contagem em escala da réplica que fez essa alteração.
ULONG
4
Reservado. Este valor pode ser ignorado.
ULONGLONG
8
Reservado. Este valor pode ser ignorado.
ULONG
4
A chave de réplica que identifica a réplica que criou esse item.
ULONGLONG
8
A contagem em escala da réplica que criou esse item.
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 tiverem 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.
Quando targetFormatVersion for SYNC_SERIALIZATION_VERSION_V3 ou superior, cada alteração conterá os elementos adicionais a seguir.
Tipo de dados Comprimento em bytes Descrição BOOL
1
Indica se existe uma ID vencedora nos dados serializados. Um valor 0 indica que não há nenhuma ID vencedora a seguir. Um valor 1 indica que há uma ID vencedora 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 vencedora de comprimento fixo.
Ou, quando as IDs de item tiverem 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 vencedora de comprimento variável.
Todas as alterações contêm os elementos adicionais a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
Os sinalizadores associados à alteração. É uma combinação de sinalizadores SYNC_CHANGE_FLAG.
ULONG
4
A estimativa de trabalho da alteração.
USHORT
2
Reservado. Esse valor é sempre 0.
BYTE
1
Indica se o conhecimento adquirido associado a essa alteração está projetado nesse item. Um valor 0 indica que o conhecimento adquirido não está projetado. Um valor 1 indica que o conhecimento adquirido está projetado.
ULONG
4
Um índice na lista de conhecimentos atuais contida nesses dados serializados. Este valor pode ser 0, indicando que um conhecimento atual não está associado a essa alteração.
ULONG
4
O número de unidades de alteração contidas na alteração. Este valor pode ser 0 e, nesse caso, não haverá nenhuma unidade de alteração a seguir.
A alteração contém uma lista com o número de unidades de alteração igual ao valor contido no ULONG anterior.
Cada unidade de alteração 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 tiverem 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 unidade de alteração contém os elementos adicionais a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
A chave de réplica que identifica a réplica que fez a alteração.
ULONGLONG
8
A contagem em escala da réplica que fez essa alteração.
ULONG
4
Reservado. Esse valor é sempre 0.
ULONGLONG
8
Reservado. Esse valor é sempre 0.
Uma seção de sincronização de recuperação. Essa seção contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
O comprimento, em bytes, da seção de sincronização de recuperação. Quando este valor for 0, não haverá nenhuma seção de sincronização de recuperação 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 representa o limite inferior das alterações do lote de alterações, quando esse lote fizer parte de uma sincronização de recuperação.
Ou, quando as IDs de item tiverem 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 representa o limite inferior das alterações do lote de alterações, quando esse lote fizer parte de uma sincronização de recuperação.
Uma seção de estimativa de trabalho. Essa seção contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição ULONG
4
A estimativa de trabalho da sessão de sincronização.
ULONG
4
A estimativa de trabalho do lote de alterações.
Uma seção de sinalizadores. Essa seção contém os elementos a seguir.
Tipo de dados Comprimento em bytes Descrição BYTE
1
Indica se o lote de alterações é o último enviado pelo provedor de origem. Um valor 0 indica que ele não é o último lote de alterações. Um valor 1 indica que ele é o último lote de alterações.
BYTE
1
Indica se o lote de alterações faz parte de uma sincronização de recuperação. Um valor 0 indica que o lote de alterações não faz parte de uma sincronização de recuperação. Um valor 1 indica que ele faz parte de uma sincronização de recuperação.
BYTE
1
Indica se o lote de alterações é filtrado. Um valor 0 indica que o lote de alterações não é filtrado. Um valor 1 indica que ele é filtrado.