Função CfConvertToPlaceholder (cfapi.h)

Converte um arquivo ou diretório não espaço reservado existente em uma árvore de diretório raiz de sincronização em um espaço reservado. Isso é útil, por exemplo, depois que um novo arquivo ou diretório local aparece em um cliente e o provedor de sincronização termina de sincronizá-lo com a nuvem. Observe que não há parâmetros para passar metadados do sistema de arquivos (carimbos de data/hora, tamanho do arquivo etc.); eles são obtidos textualmente do arquivo local.

Sintaxe

HRESULT CfConvertToPlaceholder(
  [in]                HANDLE           FileHandle,
  [in, optional]      LPCVOID          FileIdentity,
  [in]                DWORD            FileIdentityLength,
  [in]                CF_CONVERT_FLAGS ConvertFlags,
  [out, optional]     USN              *ConvertUsn,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

Parâmetros

[in] FileHandle

Identificador para o arquivo ou diretório a ser convertido.

[in, optional] FileIdentity

Um buffer de modo de usuário que contém as informações opacas de arquivo ou diretório fornecidas pelo chamador. Opcional se o chamador não estiver desidratando o arquivo ao mesmo tempo ou se o chamador estiver convertendo um diretório. FileIdentity é passado de volta para o provedor de sincronização em todos os retornos de chamada. Não é possível exceder 4 KB de tamanho.

[in] FileIdentityLength

Comprimento, em bytes, da FileIdentity.

[in] ConvertFlags

Sinalizadores de conversão de espaço reservado. ConvertFlags pode ser definido com os seguintes valores:

Sinalizador	Descrição
CF_CONVERT_FLAG_MARK_IN_SYNC	Se isso for especificado, a plataforma marcará o espaço reservado convertido como em sincronia com a nuvem após uma conversão bem-sucedida do arquivo.
CF_CONVERT_FLAG_DEHYDRATE	Isso é aplicável somente para arquivos. Quando especificado, a plataforma desidrata o arquivo depois de convertê-lo em um espaço reservado com êxito. O chamador deve adquirir um identificador exclusivo ao especificar esse sinalizador ou dados corrompidos podem ocorrer. Observe que a plataforma não valida a exclusividade do identificador.
CF_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION	Isso é aplicável somente para diretórios. Quando especificado, ele marca o diretório de espaço reservado convertido parcialmente preenchido de modo que qualquer acesso futuro a ele resultará em um retorno de chamada FETCH_PLACEHOLDERS enviado ao provedor de sincronização.
CF_CONVERT_FLAG_ALWAYS_FULL	Isso é eficaz somente em arquivos de espaço reservado. Depois que um arquivo é convertido em um espaço reservado com esse sinalizador, o espaço reservado é marcado como sempre cheio. Qualquer tentativa de desidratar esse espaço reservado falhará com o código de erro ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE	Quando especificada, a plataforma permite que um mecanismo de sincronização converta atomicamente um espaço reservado para arquivos não na nuvem (com outra marca/dados de nova análise) em um espaço reservado para arquivos de nuvem. Observe que a API normalmente falha na conversão de qualquer arquivo sem espaço reservado em um espaço reservado. A combinação (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | CF_CONVERT_FLAG_DEHYDRATE) é especialmente útil em cenários de migração quando determinados provedores estão migrando de outra plataforma para a plataforma de arquivos de nuvem e pretendem converter espaços reservados hidratados na plataforma mais antiga para espaços reservados desidratados na plataforma de arquivos de nuvem atomicamente. Apenas esse sinalizador deve ser passado para converter espaços reservados completos em espaços reservados de arquivos de nuvem. Se a plataforma mais antiga implementar arquivos completos como arquivos regulares que não são de espaço reservado, esse sinalizador não será necessário. Passar esse sinalizador em um diretório também converte diretórios em arquivos de nuvem, embora o sinalizador DEHYDRATE não se aplique aos diretórios. Mesmo quando a política CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED foi especificada com CfRegisterSyncRoot, somente processos registrados/conectados à raiz de sincronização de arquivos de nuvem têm permissão para especificar esse sinalizador. Nota: O sinalizador só terá suporte se o PlatformVersion.IntegrationNumber obtido de CfGetPlatformInfo for 0x500 ou superior.

[out, optional] ConvertUsn

Quando especificado, esse é o valor final de USN após a execução das ações de conversão.

[in, out, optional] Overlapped

Quando especificado e combinado com um FileHandle assíncrono, Overlapped permite que a plataforma execute a chamada cfConvertToPlaceholder de forma assíncrona. Consulte os Comentários para obter mais detalhes.

Se não for especificado, a plataforma executará a chamada à API de forma síncrona, independentemente de como o identificador foi criado.

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

No caso do arquivo, o chamador deve adquirir um identificador exclusivo para o arquivo se ele também pretende desidratar o arquivo ao mesmo tempo ou dados corrompidos podem ocorrer. Para minimizar o impacto nos aplicativos de usuário, é altamente recomendável que o chamador obtenha a exclusividade usando oplocks adequados (via CfOpenFileWithOplock) em vez de usar um identificador de compartilhamento-nada.

Para converter um espaço reservado:

• O arquivo ou diretório a ser convertido deve estar contido em uma árvore raiz de sincronização registrada; pode ser o próprio diretório raiz de sincronização ou qualquer diretório descendente; caso contrário, a chamada com falha com HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
• Se a desidratação for solicitada, a raiz de sincronização deverá ser registrada com uma política de hidratação válida que não seja CF_HYDRATION_POLICY_ALWAYS_FULL; caso contrário, a chamada falhará com HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
• Se a desidratação for solicitada, o espaço reservado não deverá ser fixado localmente ou a chamada com falha com HRESULT(ERROR_CLOUD_FILE_PINNED).
• Se a desidratação for solicitada, o espaço reservado deverá estar sincronizado ou a chamada com falhará com HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
• O chamador deve ter acesso WRITE_DATA ou WRITE_DAC ao arquivo ou diretório a ser convertido. Caso contrário, a operação falhará com HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

Se a API retornar HRESULT_FROM_WIN32(ERROR_IO_PENDING) ao usar Sobreposto de forma assíncrona, o chamador poderá aguardar usando GetOverlappedResult.

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

Confira também

CfOpenFileWithOplock

GetOverlappedResult