Função CfRegisterSyncRoot (cfapi.h)

Artigo
04/06/2023

Executa um registro raiz de sincronização única, permitindo que um provedor de sincronização requeira uma estrutura de árvore de diretório inteira, com raiz em SyncRootPath, como sua própria para gerenciar.

Sintaxe

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

Parâmetros

[in] SyncRootPath

O caminho para a raiz de sincronização a ser registrada.

[in] Registration

Contém informações sobre o provedor de sincronização e a raiz de sincronização a ser registrada.

ProviderName e ProviderVersion são cadeias de caracteres voltadas para o usuário final com um comprimento máximo de 255 caracteres cada.

SyncRootIdentity e FileIdentity são opcionais e, quando não fornecidos, seus comprimentos de buffer correspondentes também devem ser definidos 0 como. Eles são uma maneira de um provedor de sincronização associar dados arbitrários de forma persistente a uma raiz de sincronização.

A plataforma fornecerá SyncRootIdentity de volta ao provedor de sincronização em quaisquer retornos de chamada para o provedor de sincronização. O blob fileIdentity raiz de sincronização será fornecido somente quando o assunto do retorno de chamada for a própria raiz de sincronização.

Essa instalação é fornecida exclusivamente para a conveniência do provedor de sincronização e ambos os blobs não têm nenhum significado especial fora do provedor de sincronização.

O comprimento máximo permitido de FileIdentity é de 4 KB e o comprimento máximo permitido de SyncRootIdentity é de 64 KB. A API falha com ERROR_INVALID_PARAMETER quando o comprimento máximo é excedido.

ProviderId é um GUID destinado a identificar um provedor de sincronização específico. É opcional. Se não for fornecida, a plataforma gerará um GUID usando o hash MD5 da cadeia de caracteres ProviderName . As informações são usadas apenas para telemetria, de modo que a plataforma possa correlacionar melhor as atividades do mesmo provedor de sincronização com mais eficiência e precisão, mesmo que o provedor de sincronização registre raízes de sincronização com cadeias de caracteres ProviderName diferentes. É recomendável que um provedor de sincronização sempre forneça o mesmo GUID para todas as versões de seus produtos de sincronização. No entanto, os provedores de sincronização são livres para escolher cadeias de caracteres ProviderName diferentes para ter a melhor experiência do usuário.

[in] Policies

As políticas da raiz de sincronização a serem registradas.

[in] RegisterFlags

Sinalizadores para registrar raízes de sincronização anteriores e novas.

Sinalizador	Descrição
CF_REGISTER_FLAG_UPDATE	Um provedor de sincronização pode passar CF_REGISTER_FLAG_UPDATE para registrar novamente identidades e políticas raiz de sincronização registradas anteriormente.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	O comportamento da população de pasta/diretório sob demanda é controlado globalmente pela política de população. Esse sinalizador permite que um provedor de sincronização recuse o comportamento da população sob demanda apenas para a própria raiz de sincronização, mantendo a população sob demanda ativada para todos os outros diretórios na raiz de sincronização. Isso é útil quando o provedor de sincronização deseja preencher previamente os arquivos/diretórios filho imediatos da raiz de sincronização.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Esse sinalizador permite que um provedor de sincronização marque a raiz de sincronização para ser registrada em sincronia simultaneamente no momento do registro. A alternativa é chamar CfSetInSyncState na raiz de sincronização mais tarde.

Retornar valor

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Isso pode ser usado em um momento de instalação do provedor de sincronização, configuração pela primeira vez para um usuário individual ou quando um usuário configura outra raiz de sincronização (se houver suporte para esse cenário).

Observação

Nenhuma árvore raiz de sincronização tem permissão para se sobrepor. Como os links rígidos de diretório são proibidos pelo sistema de arquivos, a única maneira de duas raízes de sincronização se sobreporem é se elas tiverem uma relação ancestral/descendente direta. A plataforma é responsável por lembrar persistentemente todas as raízes de sincronização registradas em um determinado volume e falhar em qualquer tentativa de criar raízes de sincronização sobrepostas.

Um provedor de sincronização deve ter acesso WRITE_DATA ou WRITE_DAC à raiz de sincronização a ser registrada ou o registro falhará com ERROR_CLOUD_FILE_ACCESS_DENIED.

O provedor de sincronização deve fornecer um registro que contenha várias identidades do próprio provedor de sincronização e a raiz de sincronização a ser registrada, um conjunto de políticas que a plataforma usa para ajustar seu comportamento por raiz de sincronização e um conjunto de sinalizadores de registro que permitem um controle mais fino da operação de registro pelo provedor de sincronização.

A menos que explicitamente chamados como opcionais, todos os campos são obrigatórios e não fornecê-los resultará na falha da chamada à API com um erro de parâmetro inválido.

Todas as estruturas nas quais as extensões futuras são esperadas começam com um campo StructSize . O chamador é responsável pela contabilidade precisa do tamanho da estrutura.

Atualmente, a plataforma dá suporte a cinco tipos de Políticas:

Política de Hidratação

A política de hidratação permite que um provedor de sincronização controle como os arquivos de espaço reservado devem ser hidratados pela plataforma. Ele consiste em uma política primária e um conjunto de modificadores de política.

A política de hidratação primária tem quatro valores diferentes:

Política	Descrição
ALWAYS_FULL	A plataforma falhará (com ERROR_CLOUD_FILE_INVALID_REQUEST) qualquer operação de espaço reservado que possa resultar em um espaço reservado não totalmente hidratado, que inclui CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder com a opção de desidratação e CfConvertToPlaceholder com a opção de desidratação.
FULL	A plataforma permitirá que um espaço reservado seja desidratado. Quando a plataforma detectar o acesso a um espaço reservado desidratado, ela garantirá que o conteúdo completo do espaço reservado esteja disponível localmente antes de concluir a solicitação de E/S do usuário, mesmo que a solicitação esteja solicitando apenas 1 byte.
PROGRESSIVA	A plataforma permitirá que um espaço reservado seja desidratado. Quando a plataforma detectar o acesso a um espaço reservado desidratado, ela concluirá a solicitação de E/S do usuário assim que determinar que dados suficientes são recebidos do provedor de sincronização. No entanto, a plataforma promete continuar solicitando o conteúdo restante no espaço reservado do provedor de sincronização em segundo plano até que o conteúdo completo do espaço reservado esteja disponível localmente ou o último identificador de usuário no espaço reservado seja fechado. Nota: Os provedores de sincronização que optam por PROGRESSIVE podem não assumir que os retornos de chamada de hidratação chegam sequencialmente do deslocamento `0`. Em outras palavras, espera-se que os provedores de sincronização com a política PROGRESSIVA lidem com buscas aleatórias no espaço reservado.
PARTIAL	Essa política é muito semelhante à PROGRESSIVA, com a única diferença sendo a falta de hidratação contínua em segundo plano.

No momento, há suporte para três modificadores de política. Em geral, os modificadores podem ser misturados e combinados com quaisquer políticas primárias e outros modificadores de política, desde que a combinação não seja autoconfiábil.

Modificador	Descrição
VALIDATION_REQUIRED	Esse modificador de política oferece duas garantias a um provedor de sincronização. Primeiro, ele garante que os dados retornados pelo provedor de sincronização sempre sejam persistidos no disco antes de serem retornados ao aplicativo do usuário. Em segundo lugar, ele permite que o provedor de sincronização recupere os mesmos dados retornados anteriormente para a plataforma e valide sua integridade. Somente após uma confirmação bem-sucedida da integridade pelo provedor de sincronização, a plataforma concluirá a solicitação de E/S do usuário. Esse modificador ajuda a dar suporte à integridade de dados de ponta a ponta ao custo de E/S de disco extra.
STREAMING_ALLOWED	Esse modificador de política concede à plataforma a permissão para não armazenar dados retornados por um provedor de sincronização em discos locais. Esse modificador de política é mutuamente exclusivo com VALIDATION_REQUIRED. A API falha com ERROR_INVALID_PARAMETER quando ambos os sinalizadores são especificados.
AUTO_DEHYDRATION_ALLOWED	Esse modificador de política concede à plataforma a permissão para desidratar espaços reservados de arquivo na nuvem em sincronia sem a ajuda de provedores de sincronização. Sem esse sinalizador, a plataforma não tem permissão para chamar CfDehydratePlaceholder diretamente. Em vez disso, a única maneira com suporte de desidratar um espaço reservado de arquivo de nuvem é limpar o atributo fixado do arquivo e definir o atributo desafixado do arquivo e, em seguida, a desidratação real será executada de forma assíncrona pelo mecanismo de sincronização depois que ele receber a notificação de alteração de diretório nos dois atributos. Quando esse sinalizador for especificado, a plataforma terá permissão para invocar CfDehydratePlaceholder diretamente em qualquer espaço reservado de arquivo na nuvem em sincronia. É recomendável que os provedores de sincronização ofereçam suporte à desidratação automática.

Política de População

A política de população permite que um provedor de sincronização controle como o namespace de espaço reservado (diretórios e arquivos) deve ser criado pela plataforma. Atualmente, há três políticas primárias sem modificadores definidos:

Política	Descrição
ALWAYS_FULL	A plataforma pressupõe que o espaço de nome completo esteja sempre disponível localmente. Ele nunca encaminhará nenhuma solicitação de enumeração de diretório para o provedor de sincronização.
FULL	Quando a plataforma detectar o acesso em um diretório não totalmente preenchido, ela solicitará que o provedor de sincronização retorne todas as entradas no diretório antes de concluir a solicitação do usuário.
PARTIAL	Quando a plataforma detectar o acesso em um diretório não totalmente preenchido, ela solicitará apenas as entradas exigidas pelo aplicativo de usuário do provedor de sincronização.

Política de Acompanhamento do InSync

A política InSync permite que um provedor de sincronização controle quando a plataforma deve limpar o estado de sincronização em um espaço reservado. Além de sempre limpar a sincronização em qualquer modificação de dados, a plataforma atualmente pode limpar a sincronização em alterações de qualquer combinação de três atributos de arquivo (ReadOnly, System e Hidden) e duas vezes de arquivo (CreateTime e LastWriteTime). Essas políticas podem ser aplicadas a arquivos e diretórios separadamente.

Política de hardlink

Por padrão, a plataforma não permite que links rígidos sejam criados em nenhum espaço reservado. Os provedores de sincronização que são capazes de lidar com links físicos, no entanto, podem instruir a plataforma a habilitar o suporte por meio da política ALLOWED . Com essa política, os aplicativos podem criar tantos links rígidos quanto o sistema de arquivos dá suporte, desde que os links estejam na mesma raiz de sincronização ou sem raiz de sincronização. A plataforma forçará um espaço reservado a ser hidratado quando o primeiro link fora de sincronização-raiz for introduzido e reverter um espaço reservado para o arquivo normal quando seu último link na sincronização-raiz for removido. A criação de hardlink que não é compatível com a política falhará com STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. As operações de espaço reservado que não são compatíveis com a política também falharão com STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

Política de Gerenciamento de Espaço Reservado

Por padrão, somente um provedor de sincronização pode executar operações de gerenciamento de espaço reservado em uma raiz de sincronização. Os processos do provedor de não sincronização só poderão executar operações de gerenciamento de espaço reservado se a raiz de sincronização estiver inativa, ou seja, quando a raiz de sincronização não estiver conectada por nenhum provedor de sincronização. Essas políticas, quando habilitadas, permitem que processos de provedor não sincronizados executem as respectivas operações de gerenciamento de espaço reservado em uma raiz de sincronização ativa. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT é a política padrão que permite que apenas um provedor de sincronização conectado execute operações de gerenciamento de espaço reservado. As seguintes políticas podem ser especificadas em qualquer combinação:

Política	Descrição
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Quando essa política é especificada durante o registro, qualquer processo pode criar um espaço reservado em uma raiz de sincronização ativa chamando CfCreatePlaceholders.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Quando essa política é especificada durante o registro, qualquer processo pode converter um arquivo ou um diretório dentro de uma raiz de sincronização ativa em um espaço reservado chamando CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Quando essa política é especificada durante o registro, qualquer processo pode atualizar um espaço reservado dentro de uma raiz de sincronização ativa chamando CfUpdatePlaceholder.

Observação

Esses sinalizadores só têm suporte se PlatformVersion.IntegrationNumber obtido de CfGetPlatformInfo for 0x310 ou superior.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10, versão 1709 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2016 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	cfapi.h
Biblioteca	CldApi.lib
DLL	CldApi.dll