Filtrando dados de sincronização

Artigo
08/18/2010

Um filtro é usado para restringir os dados que são sincronizados. Em geral, o provedor de origem aplica o filtro durante a enumeração de alterações para restringir as alterações enviadas. O Sync Framework suporta os seguintes tipos de filtro.

Os filtros de item restringem os dados de sincronização a um subconjunto de itens, como sincronizar apenas arquivos .txt entre duas pastas de arquivos, ignorando arquivos de outros tipos. Os itens não são alterados de forma a fazer um item existente ser inserido ou removido do filtro. É simples usar os filtros de item, mas os metadados usados para a sincronização aumentam proporcionalmente ao número de itens existentes no escopo de sincronização.
Os filtros de unidade de alteração restringem os dados de sincronização a um subconjunto de unidades de alteração, como para sincronizar apenas os campos name e phone number de um contato, ignorando as unidades de alteração restantes.
Os filtros personalizados restringem os dados de sincronização de forma desconhecida ao Sync Framework. Ao longo do tempo, os itens podem ser inseridos e removidos dos filtros. O Sync Framework define metadados, interfaces e classes adicionais que dão suporte de forma eficiente a filtros personalizados, mantendo o tamanho geral dos metadados pequeno.

O filtro pode ser definido pelo aplicativo de sincronização ou pelo provedor de origem ou de destino, ou pode ser negociado entre os provedores de origem e de destino.

O filtro será usado pelo provedor de origem quando ele detectar alterações. Alterar os lotes criados durante a detecção de alterações incluirá somente os dados de sincronização que passarem o filtro.

O filtro também pode ser usado pelo provedor de destino quando ele aplicar alterações. As alterações aplicadas à réplica de destino incluem apenas os dados de sincronização que passarem o filtro.

Controlando os itens a serem sincronizados

Um filtro de item define quais alterações de item são enviadas pelo provedor de origem durante a enumeração de alterações. Como o modo em que os itens são filtrados depende do tipo de dados contidos no escopo de sincronização, o Sync Framework permite que o provedor de origem defina o mecanismo de filtragem. Se for necessária uma comunicação sobre o filtro entre o provedor e o aplicativo de sincronização, ela poderá ser estabelecida usando qualquer mecanismo apropriado.

Quando o provedor de origem filtrar alterações de item, o Sync Framework exigirá que o provedor de origem anexe informações sobre o filtro para todos os objetos do lote de alterações enviados durante a enumeração de alterações. A presença de informações de filtro de item no objeto do lote de alterações informa ao Sync Framework que uma sincronização filtrada está ocorrendo, de forma que o Sync Framework pode tratar corretamente o conhecimento para o lote de alterações filtrado. Se o provedor de origem filtrar os itens incluídos em um lote de alterações, mas não especificar informações de filtro de item para o objeto do lote de alterações, talvez o Sync Framework não possa manipular o conhecimento corretamente.

Quando o provedor de origem usa um filtro para restringir os itens contidos em um lote de alterações, o provedor deve anexar informações sobre o filtro ao objeto ChangeBatch (para código gerenciado) ou ISyncChangeBatch (para código não gerenciado). As informações de filtro são representadas por um objeto ItemListFilterInfo (para código gerenciado) ou um objeto ISyncFilterInfo que tem o sinalizador SYNC_FILTER_INFO_FLAG_ITEM_LIST definido (para código não gerenciado). No código não gerenciado, o provedor cria um objeto ISyncFilterInfo usando IProviderFilteredSyncServices::CreateFilterInfo. As informações de filtro são anexadas ao lote de alterações usando ChangeBatch(SyncIdFormatGroup, SyncKnowledge, ForgottenKnowledge, FilterInfo) (para código gerenciado) ou IProviderFilteredSyncServices::CreateFilteredEnumerationChangeBatch (para código não gerenciado) a fim de criar o objeto do lote de alterações.

Para obter mais informações sobre como usar a filtragem de itens, consulte Como filtrar itens enumerados.

Controlando quais unidades de alteração são sincronizadas

Um filtro de unidade de alteração define quais alterações serão incluídas para cada alteração de item enviada pelo provedor de origem durante a enumeração de alterações. Um filtro de unidade de alteração é útil quando uma réplica armazenar apenas um subconjunto das unidades de alteração definido para os itens no escopo.

Por exemplo, uma comunidade de sincronização troca informações de contato e define unidades de alteração para name, phone number e address. Uma réplica na comunidade é um dispositivo móvel que só pode armazenar name e phone number. Essa réplica usa um filtro de unidade de alteração para especificar que só controla o conhecimento para essas duas unidades de alteração. Quando uma réplica de origem sincronizar dados para a réplica de dispositivo, ela usará o filtro de unidade de alteração para enviar informações apenas sobre as unidades de alteração name e phone number. O conhecimento adquirido do provedor de origem é projetado no filtro da unidade de alteração de modo que o conhecimento na réplica de dispositivo contenha conhecimento somente das unidades de alteração name e phone number. De modo semelhante, quando uma alteração é feita localmente no dispositivo e o dispositivo age subsequentemente como a réplica de origem em uma sessão de sincronização, a réplica que recebe as alterações atualiza seu conhecimento somente para o conjunto especificado de unidades de alteração.

Quando um filtro de unidade de alteração é usado, o Sync Framework projeta o conhecimento adquirido para o lote de alterações no conjunto de unidades de alteração especificado pelo filtro de forma que o conhecimento adquirido do lote de alterações só contenha informações sobre o conjunto especificado de unidades de alteração.

Para filtrar alterações de unidade de alteração, o provedor de origem cria um objeto ChangeUnitListFilterInfo (para código gerenciado) ou IChangeUnitListFilterInfo (para código não gerenciado) e especifica o conjunto de unidades de alteração que são sincronizadas. No código não gerenciado, o objeto IChangeUnitListFilterInfo é criado especificando SYNC_FILTER_INFO_FLAG_CHANGE_UNIT_LIST para o método IProviderFilteredSyncServices::CreateFilterInfo. O provedor de origem anexa as informações de filtro ao lote de alterações usando ChangeBatch(SyncIdFormatGroup, SyncKnowledge, ForgottenKnowledge, FilterInfo) (para código gerenciado) ou IProviderFilteredSyncServices::CreateFilteredEnumerationChangeBatch (para código não gerenciado) a fim de criar o objeto do lote de alterações.

Para obter mais informações sobre como usar um filtro de unidade de alteração, consulte Como filtrar unidades de alteração enumeradas.

Controlando o que é sincronizado usando um filtro personalizado

Um filtro personalizado é definido externamente ao Sync Framework, normalmente por um desenvolvedor de provedor, mas ele também pode ser definido por terceiros. O Sync Framework não tem conhecimento de como o filtro determina o que é incluído no escopo de sincronização. Um filtro personalizado pode ser definido de forma que os itens sejam inseridos e removidos do filtro ao longo do tempo. Por exemplo, em uma réplica que armazena arquivos de mídia, é possível definir um filtro que inclua todos os arquivos classificados como três estrelas ou mais. Quando o usuário altera a classificação em um arquivo, ele pode ser inserido ou removido do filtro.

Lembre-se de que filtros personalizados não podem ser usados por provedores simples nem por provedores que relatam conflitos de restrição ou usam o serviço de aplicação de alterações, ou podem ocorrer resultados inesperados.

Para dar suporte de forma eficiente a filtros personalizados, o Sync Framework define vários conceitos novos.

A réplica de acompanhamento de filtro mantém metadados que definem quais itens e unidades de alteração estão atualmente em um filtro acompanhado, quais itens e unidades de alteração foram inseridos e removidos recentemente do filtro acompanhado, e filtra o conhecimento esquecido que abrange todos os itens e unidades de alteração que não estão no filtro acompanhado e que foram esquecidos. O acompanhamento de um filtro não afeta os itens que estão armazenados em uma réplica. Uma réplica pode acompanhar vários filtros enquanto armazena todos os itens do escopo de sincronização. Normalmente, uma réplica de acompanhamento de filtro pode fornecer um lote de alterações filtrado para qualquer dos filtros acompanhados.
A réplica filtrada armazena somente dados de itens e unidades de alteração que estão no filtro, além dos metadados de itens e unidades de alteração que estavam no filtro mas que foram removidos. Uma réplica filtrada sempre acompanha o filtro que usa e pode acompanhar também filtros adicionais. Um provedor de destino filtrado pode solicitar uma enumeração de alterações filtrada do provedor de origem ou pode solicitar uma enumeração de alterações completa e filtrar as alterações durante a aplicação de alterações.
Fantasmas são itens ou unidades de alteração em uma réplica filtrada que estavam no filtro e foram removidos. A réplica filtrada armazena metadados para fantasmas, mas não armazena dados de itens ou unidades de alteração.
O conhecimento esquecido do filtro define um ponto inicial para o acompanhamento de filtro. Uma réplica de acompanhamento de filtro pode economizar espaço de armazenamento removendo fantasmas e avançando o conhecimento esquecido do filtro para conter a versão mais superior dos fantasmas removidos. O conhecimento esquecido do filtro também é usado quando uma réplica começa a acompanhar um filtro depois que ele está em uso por outras réplicas na comunidade de sincronização.

Acompanhando filtros

É recomendável que todas as réplicas em uma comunidade de sincronização acompanhem os filtros usados na comunidade. Quando uma réplica filtrada recebe uma enumeração de alterações filtrada de uma réplica de acompanhamento de filtro, o conhecimento da réplica filtrada é mantido pequeno. Quando uma réplica filtrada recebe uma enumeração de alterações filtrada de uma réplica que não acompanha o filtro, o tamanho do conhecimento aumenta proporcionalmente ao número de alterações enviadas.

Para obter mais informações sobre rastreamento de filtros, consulte Como rastrear filtros e enumerar alterações filtradas.

Metadados de filtro

Para acompanhar um filtro, uma réplica armazena metadados de filtro para cada item ou unidade de alteração da réplica. Os metadados de filtro contêm os elementos da seguinte tabela:

Está no filtro	Versão de movimento
Indica se o item ou a unidade de alteração está no filtro.	A versão da alteração que fez o item ser movido em relação ao filtro. Quando é criado um item e ele está no filtro, essa versão é definida como a versão de criação do item. Quando um item nunca esteve no filtro, essa versão é definida como (0,0).

Quando uma réplica começa a acompanhar um filtro, todos os itens ou unidades de alteração devem ser avaliados em relação ao filtro. Se um item ou uma unidade de alteração está no filtro, seus metadados de filtro devem indicar isso e sua versão de movimento deve ser definida como a versão de alteração mais recente do item ou da unidade de alteração. Se um item não está no filtro, seus metadados de filtro devem indicar isso e sua versão de movimento deve ser definida como (0,0).

Uma réplica de acompanhamento de filtro também pode armazenar o conhecimento esquecido de cada filtro que ela acompanha. Quando uma réplica de acompanhamento de filtro acompanha um filtro de sua origem, ela não armazena o conhecimento esquecido do filtro, a menos que receba dados de sincronização de uma réplica que não acompanha o filtro. Quando uma réplica de acompanhamento de filtro começa a acompanhar um filtro algum tempo após ele ter sido originado, ela deve inicializar o conhecimento esquecido do filtro para o conhecimento atual da réplica. Quando marcas de exclusão e metadados de alteração de filtro são removidos em uma réplica, o conhecimento esquecido do filtro pode ser descartado e o conhecimento esquecido, usado.

Negociando filtros acompanhados

Um provedor de acompanhamento de filtro deve implementar IFilterTrackingProvider (para código gerenciado) ou IFilterTrackingProvider (para código não gerenciado). Essa interface é usada para comunicar os filtros que são acompanhados na réplica de origem e na réplica de destino. A réplica de origem envia metadados de filtro para os filtros que são acompanhados na réplica de origem e na réplica de destino.

Quando os dois provedores em uma sessão de sincronização são provedores de acompanhamento de filtro, o Sync Framework faz a mediação da negociação de quais filtros são acompanhados pelos dois provedores. Os filtros acompanhados são negociados entre dois provedores de acompanhamento de filtro executando as seguintes etapas:

Depois de chamar BeginSession (para código gerenciado) ou IKnowledgeSyncProvider::BeginSession (para código não gerenciado), o Sync Framework chama SpecifyTrackedFilters (para código gerenciado) ou IFilterTrackingProvider::SpecifyTrackedFilters (para código não gerenciado) no provedor de destino.
O provedor de destino enumera sua lista de filtros acompanhados e passa cada um para o representante RequestTrackedFilterCallback (para código gerenciado) ou para o método IFilterRequestCallback::RequestFilter do objeto IFilterRequestCallback (para código não gerenciado) especificado na chamada de SpecifyTrackedFilters.
Para cada filtro especificado pelo provedor de destino, o Sync Framework chama TryAddTrackedFilter (para código gerenciado) ou IFilterTrackingProvider::AddTrackedFilter (para código não gerenciado) no provedor de origem.
O provedor de origem mantém uma lista de filtros acompanhados pelo provedor de destino e retorna um valor que indica se o filtro especificado é acompanhado.
O Sync Framework passa esse valor para o provedor de destino.

Enviando metadados de filtros acompanhados

Quando o provedor de destino acompanha filtros que também são acompanhados pelo provedor de origem, o provedor de origem deve enviar metadados de filtro para os filtros acompanhados mutuamente. Para fazer isso, adicione as seguintes alterações à implementação do provedor de origem de GetChangeBatch (para código gerenciado) ou IKnowledgeSyncProvider::GetChangeBatch (para código não gerenciado):

Adicione um objeto FilterKeyMap ao objeto ChangeBatch definindo a propriedade FilterKeyMap (para código gerenciado) ou adicione um objeto IFilterKeyMap ao objeto ISyncChangeBatchWithFilterKeyMap chamando ISyncChangeBatchWithFilterKeyMap::SetFilterKeyMap (para código não gerenciado). O objeto do mapa de chave de filtro contém os filtros acompanhados pelo provedor de origem e pelo provedor de destino. A propriedade FilterKeyMap deve ser definida (para código gerenciado) ou o método SetFilterKeyMap deve ser chamado (para código não gerenciado) antes de os grupos serem iniciados no lote de alterações.
Para cada grupo no lote de alterações, adicione o conhecimento esquecido dos filtros acompanhados chamando SetFilterForgottenKnowledge (para código gerenciado) ou ISyncChangeBatchWithFilterKeyMap::SetFilterForgottenKnowledge (para código não gerenciado).
Envie os metadados de alteração do filtro para cada item ou unidade de alteração que foi inserida ou removida de um filtro acompanhado. Os metadados de alteração de filtro são adicionados a uma alteração chamando AddFilterChange (para código gerenciado) ou IFilterTrackingSyncChangeBuilder::AddFilterChange (para código não gerenciado). As propriedades FilterChange (para código gerenciado) ou os valores SYNC_FILTER_CHANGE (para código não gerenciado) indicam se o item foi inserido ou removido do filtro e a versão da alteração que causou o movimento. Os metadados de alteração de filtro são adicionados somente quando a versão de movimento não está contida no conhecimento de destino do item. Quando são usadas unidades de alteração, os metadados de alteração do filtro devem ser adicionados se a versão de movimento não está contida no conhecimento de destino de nenhuma das unidades de alteração. Lembre-se de que as versões de movimento são tratadas como versões de item até mesmo quando são usadas unidades de alteração; assim, o confinamento deve ser verificado usando uma forma do método Contains (para código gerenciado) ou do método ISyncKnowledge::ContainsChange (para código não gerenciado) que contém uma versão de item e não uma que usa uma versão da unidade de alteração.
Quando são usadas unidades de alteração e pelo menos uma alteração de unidade de alteração não está contida no conhecimento de destino, chame ContainsMarker (para código gerenciado) ou IKnowledgeWithMarkers::ContainsAllChangeUnitsRequiredMarker (para código não gerenciado) no conhecimento de destino, especificando AllChangeUnitsRequired e a ID do item proprietário (para código gerenciado ou para código não gerenciado). Se esse método indicar que todas as unidades de alteração são necessárias, envie todas as unidades de alteração para o item e chame SetAllChangeUnitsPresent no objeto ItemChange (para código gerenciado) ou IFilterTrackingSyncChangeBuilder::SetAllChangeUnitsPresentFlag (para código não gerenciado).

Enviando alterações filtradas

Normalmente, um provedor de origem que representa uma réplica de acompanhamento de filtro pode enumerar lotes de alteração filtrados para qualquer dos filtros acompanhados. O filtro pode ser identificado pelo aplicativo, usando um mecanismo personalizado entre o aplicativo e o provedor de origem, ou pode ser negociado entre os provedores de origem e de destino. A negociação de Filtro é descrita posteriormente neste documento.

Para enviar um lote de alterações filtrado, adicione os seguintes elementos ao método GetChangeBatch do provedor de origem:

Crie um objeto CustomFilterInfo (para código gerenciado) ou ICustomFilterInfo (para código não gerenciado) que contém o filtro usado para a sincronização. Crie um objeto do lote de alterações filtrado passando o objeto de informações de filtro para o construtor ChangeBatch do lote de alterações apropriado (para código gerenciado) ou chamando IProviderFilteredSyncServices::CreateFilteredEnumerationChangeBatch (para código não gerenciado). Além disso, passe o conhecimento esquecido do filtro ao criar o objeto do lote de alterações, em vez do conhecimento esquecido da réplica.
Quando um item ou uma unidade de alteração estava anteriormente, mas não está atualmente no filtro, especifique a propriedade ChangeKind como Ghost (para código gerenciado) ou passe o sinalizador SYNC_CHANGE_FLAG_GHOST para ISyncChangeBatchBase::AddItemMetadataToGroup (para código não gerenciado).
Quando o tipo de filtragem do provedor de destino for CurrentItemsOnly (para código gerenciado) ou FT_CURRENT_ITEMS_ONLY (para código não gerenciado), inclua um item no lote de alterações somente se ele estiver no filtro. Ou seja, não envie fantasmas.
Quando o tipo de filtragem do provedor de destino for CurrentItemsAndVersionsForMovedOutItems (para código gerenciado) ou FT_CURRENT_ITEMS_AND_VERSIONS_FOR_MOVED_OUT_ITEMS (para código não gerenciado), inclua os itens que estão no filtro e os itens que foram removidos. As informações removidas devem ser enviadas quando um item ou uma unidade de alteração estava anteriormente no filtro, não está atualmente no filtro e as versões da alteração que removeu o item ou a unidade de alteração do filtro não está contida no conhecimento de destino.

Aplicando metadados de filtro

Quando um provedor de destino representa um provedor de acompanhamento de filtro e usa um aplicador de alterações para aplicar alterações à réplica de destino, o provedor de destino deve implementar IFilterTrackingNotifyingChangeApplierTarget (para código gerenciado) ou IFilterTrackingNotifyingChangeApplierTarget (para código não gerenciado). Essa interface contém métodos usados pelo Sync Framework para obter o mapa de chave e o conhecimento esquecido dos filtros acompanhados. Ela também contém o método SaveKnowledgeWithFilterForgottenKnowledge (para código gerenciado) ou IFilterTrackingNotifyingChangeApplierTarget::SaveKnowledgeWithFilterForgottenKnowledges (para código não gerenciado), que o Sync Framework chama em vez de StoreKnowledgeForScope (para código gerenciado) ou ISynchronousNotifyingChangeApplierTarget::SaveKnowledge (para código não gerenciado) para provedores de acompanhamento de filtro. O Sync Framework usa esse método para enviar o conhecimento atualizado, o conhecimento esquecido e o conhecimento esquecido do filtro para o provedor depois que um lote de alterações é aplicado.

Além de implementar IFilterTrackingNotifyingChangeApplierTarget, o método SaveItemChange ou SaveChangeWithChangeUnits (para código gerenciado) ou o método ISynchronousNotifyingChangeApplierTarget::SaveChange ou ISynchronousNotifyingChangeApplierTarget::SaveChangeWithChangeUnits (para código não gerenciado) do provedor de destino deve ser atualizado para executar as etapas a seguir:

Obtenha os metadados de alteração de filtro para cada filtro rastreado chamando GetFilterChange(UInt32) (para código gerenciado) ou ISyncChangeWithFilterKeyMap::GetFilterChange (para código não gerenciado) no objeto de alteração.
Quando os metadados de alteração de filtro estiverem presentes, verifique se eles não estão obsoletos. Uma alteração de filtro está obsoleta quando sua versão de movimento está contida no conhecimento de destino do item. Quando são usadas unidades de alteração, uma alteração de filtro está obsoleta somente quando a versão de movimento está contida no conhecimento de destino de todas as unidades de alteração. Se a alteração do filtro está obsoleta, não a aplique à réplica de destino.
Quando os metadados de alteração de filtro estão presentes e não são obsoletos, verifique se eles não estão em conflito com as informações de alteração de filtro presentes na réplica de destino. Para verificar conflitos, execute as seguintes etapas:
1. Obtenha a versão de movimento armazenada atualmente para o item ou a unidade de alteração na réplica de destino.
2. Verifique se a versão de movimento está contida no conhecimento atual do item ou no conhecimento atual de todas as alterações de unidades de alteração associadas com o item.
3. Se a versão de movimento não estiver contida no conhecimento atual apropriado, a alteração de filtro estará em conflito. O provedor de destino deve resolver isso da forma apropriada e atribuir uma nova versão de movimento à alteração.
4. Se nenhum conflito for detectado na versão de movimento, verifique o sinalizador de movimento da alteração de filtro de origem em relação ao sinalizador de movimento do item de destino ou da unidade de alteração. Se o valor do sinalizador for inconsistente, o provedor de destino deverá avaliar o item ou a unidade de alteração em relação ao filtro e atribuir o valor do sinalizador de movimento correto junto com uma nova versão de movimento.
5. Se nenhum conflito de qualquer tipo for detectado, armazene os metadados de alteração de filtro junto com os metadados do item.
Quando os metadados de alteração do filtro não estão presentes em um filtro rastreado ou em um filtro rastreado pela réplica de destino mas não pela réplica de origem, avalie a alteração em relação ao filtro no destino. Atualize os metadados do filtro de forma a incluir se o item está no filtro e atualize a versão de movimento para a versão da alteração se a alteração fez o item mover-se em relação ao filtro. Quando há várias unidades de alteração associadas a um filtro e uma alteração a algum deles faz o item se mover em relação ao filtro, crie uma nova versão local e defina a nova versão como a versão de movimento do item e como a versão de alteração de todas as unidades de alteração associadas ao filtro.

Réplicas filtradas

Uma réplica filtrada armazena somente dados de itens e unidades de alteração que estão no seu filtro, além dos fantasmas, que são metadados de itens e unidades de alteração que estavam no filtro mas que foram removidos. Uma réplica filtrada também acompanha seu filtro e pode acompanhar outros filtros. Uma réplica filtrada pode negociar um filtro com o provedor de origem; nesse caso, o provedor de origem gera um lote de alterações filtrado. Se o provedor de origem não puder gerar um lote de alterações filtrado, o provedor filtrado poderá filtrar as alterações e aplicar apenas as que estiverem no seu filtro.

Para obter mais informações sobre como implementar uma réplica filtrada, consulte Como filtrar uma réplica.

Enumerando itens inseridos no filtro

Uma réplica filtrada implementa o IFilteredReplicaNotifyingChangeApplierTarget (para código gerenciado) ou a interface IFilteredReplicaNotifyingChangeApplierTarget (para código não gerenciado). Essa interface contém o GetNewMoveInItems (para código gerenciado) ou IFilteredReplicaNotifyingChangeApplierTarget::GetNewMoveins (para código não gerenciado) que o Sync Framework usa para obter os itens que foram inseridos no filtro depois de um determinado momento. Um item é adicionado à lista que é retornada desse método quando o item está ativo, está no filtro e a versão de movimento do item não está contida no conhecimento especificado para o método.

Enviando alterações não filtradas

Quando a réplica filtrada é a réplica de origem e a réplica de destino não solicita uma enumeração de alterações filtrada, ou quando um filtro não for negociado com êxito entre as duas réplicas, a réplica de origem enumera alterações como se não fosse filtrada. Isso difere do processo de envio de alterações filtradas das seguintes formas:

Um lote de alterações não filtrado é criado.
O conhecimento esquecido da réplica é passado ao criar o lote de alterações, mas não o conhecimento esquecido de filtro como quando alterações filtradas são enviadas.

Aplicando alterações filtradas

Quando o provedor de destino usa um aplicador de alterações, ele deve indicar se o item ou a unidade de alteração de destino é um fantasma ao enviar versões de destino para o aplicador de alterações. Para fazer isso, especifique Ghost para a propriedade ChangeKind (para código gerenciado) ou passe o sinalizados SYNC_CHANGE_FLAG_GHOST para IDestinationChangeVersionsBuilder::AddItemMetadata (para código não gerenciado) quando o item for um fantasma na réplica de destino. Um item é um fantasma quando existem metadados para o item no repositório de metadados de destino, o item não foi excluído e não existe nenhum dado para o item no repositório de destino.

Quando as alterações do provedor de origem não são filtradas, o provedor de destino avalia todas as alterações enviadas pelo provedor de origem em relação ao filtro da réplica de destino. O provedor de destino aplica as alterações que passam pelo filtro e atualiza todos os fantasmas afetados. O provedor de destino exclui todas as alterações ignoradas do conhecimento do lote de alterações.

O provedor de destino também deve fazer as seguintes alterações ao seu método SaveItemChange ou SaveChangeWithChangeUnits (para código gerenciado), ou ISynchronousNotifyingChangeApplierTarget::SaveChange ou ISynchronousNotifyingChangeApplierTarget::SaveChangeWithChangeUnits (para código não gerenciado).

Manipule as ações CreateGhost e UpdateGhost (para código gerenciado) ou SSA_CREATE_GHOST ou SSA_UPDATE_GHOST (para código não gerenciado) criando ou atualizando os metadados de um fantasma. Também é necessário atualizar os metadados de alteração de filtro, se aplicável.
Manipule a ação MarkItemAsGhost (para código gerenciado) ou SSA_GHOST_ITEM (para código não gerenciado) removendo os dados do item ou da unidade de alteração e atualizando os metadados do item ou da unidade de alteração a fim de refletir a alteração.
Manipule a ação UnmarkItemAsGhost (para código gerenciado) ou SSA_UNGHOST_ITEM (para código não gerenciado) recuperando os dados do item ou da unidade de alteração, armazenando os dados na réplica de destino e atualizando os metadados a fim de refletir a alteração.
Manipule a ação DeleteGhostAndStoreTombstone (para código gerenciado) ou SSA_DELETE_GHOST_AND_STORE_TOMBSTONE (para código não gerenciado) marcando os metadados do fantasma como excluídos.

Limpando fantasmas

Para liberar espaço de armazenamento em uma réplica filtrada, é possível remover os fantasmas. Quando um fantasma é removido, o conhecimento esquecido do filtro deve ser atualizado passando a versão de movimento do fantasma para o método ForgetTo (para código gerenciado) ou IForgottenKnowledge::ForgetToVersion (para código não gerenciado) do conhecimento esquecido de filtro.

Negociando o filtro

O provedor de destino pode especificar o filtro usado pelo provedor de origem durante a enumeração de alterações. O provedor de origem pode aceitar ou negar o filtro solicitado pelo provedor de destino. O provedor de destino pode continuar a solicitar filtros até encontrar um que seja aceito pelo provedor de origem. Essa negociação é mediada pelo Sync Framework. O filtro pode ser do tipo que for mais apropriado para os provedores.

Para participar da negociação de filtro, o provedor de origem deve implementar ISupportFilteredSync (para código gerenciado) ou ISupportFilteredSync (para código não gerenciado) e o provedor de destino deve implementar IRequestFilteredSync (para código gerenciado) ou IRequestFilteredSync (para código não gerenciado).

A negociação de filtro é obtida por meio das seguintes etapas:

Antes de o provedor de origem começar a enumerar alterações e depois de chamar BeginSession (para código gerenciado) ou IKnowledgeSyncProvider::BeginSession (para código não gerenciado), o Sync Framework inicia a negociação de filtro chamando o método SpecifyFilter (para código gerenciado) ou IRequestFilteredSync::SpecifyFilter (para código não gerenciado) no provedor de destino.
Durante o processamento de SpecifyFilter, o provedor de destino passa filtros para o representante FilterRequestCallback (para código gerenciado) ou o método IFilterRequestCallback::RequestFilter (para código não gerenciado) especificado pelo Sync Framework. Quando o provedor de destino não acompanha o filtro solicitado, especifica um tipo de filtragem CurrentItemsOnly (para código gerenciado) ou FT_CURRENT_ITEMS_ONLY (para código não gerenciado). Quando o provedor de destino acompanha o filtro solicitado, especifica um tipo de filtragem CurrentItemsAndVersionsForMovedOutItems (para código gerenciado) ou FT_CURRENT_ITEMS_AND_VERSIONS_FOR_MOVED_OUT_ITEMS (para código não gerenciado).
Durante o processamento de FilterRequestCallback (para código gerenciado) ou RequestFilter (para código não gerenciado), o Sync Framework chama o método TryAddFilter(Object) (para código gerenciado) ou ISupportFilteredSync::AddFilter (para código não gerenciado) do provedor de origem. Se o provedor de origem não oferecer suporte ao filtro solicitado, o provedor de destino poderá continuar solicitando filtros até encontrar um que tenha suporte.
Se o provedor de destino não puder localizar um filtro aceito pelo provedor de origem, poderá encerrar a sincronização lançando SyncInvalidOperationException (para código gerenciado) ou retornando um código de erro, como SYNC_E_FILTER_NOT_SUPPORTED (para código não gerenciado).

Quando um filtro tiver sido negociado com êxito, o provedor de origem o usará para determinar os itens a serem incluídos durante a enumeração de alterações.

Para obter mais informações sobre como negociar filtros, consulte Como negociar um filtro.