Função CfUpdatePlaceholder (cfapi.h)

Essa API altera as características de um espaço reservado existente. O uso mais provável dessa API é quando um arquivo foi modificado na nuvem e o provedor de sincronização deseja incorporar os efeitos dessa modificação em um espaço reservado. Para dar suporte a esse cenário, o chamador pode passar novos metadados do sistema de arquivos (carimbos de data/hora, tamanho do arquivo etc.) a serem aplicados e/ou um novo blob FileIdentity .

Sintaxe

HRESULT CfUpdatePlaceholder(
  [in]                HANDLE               FileHandle,
  [in, optional]      const CF_FS_METADATA *FsMetadata,
  [in, optional]      LPCVOID              FileIdentity,
  [in]                DWORD                FileIdentityLength,
  [in, optional]      const CF_FILE_RANGE  *DehydrateRangeArray,
  [in]                DWORD                DehydrateRangeCount,
  [in]                CF_UPDATE_FLAGS      UpdateFlags,
  [in, out, optional] USN                  *UpdateUsn,
  [in, out, optional] LPOVERLAPPED         Overlapped
);

Parâmetros

[in] FileHandle

FileHandle é um identificador para o arquivo ou diretório cujos metadados devem ser atualizados. No caso de um 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 sobre os 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.

[in, optional] FsMetadata

FsMetadata contém metadados do sistema de arquivos sobre o espaço reservado a ser atualizado, incluindo todos os carimbos de data/hora, atributos de arquivo e tamanho do arquivo (opcional para diretórios). Esse é um campo opcional. Se não for fornecido, todos esses campos permanecerão intactos após a chamada.

• Um 0 valor em um campo de carimbo de data/hora (CreationTime, LastAccessTime, LastWriteTime e ChangeTime) significa nenhuma alteração no carimbo de data/hora atual no arquivo.
• Um 0 valor em FileAttributes significa que não há alteração nos atributos de arquivo atuais no arquivo.
• Não há nenhum valor especial em FileSize; um 0 valor em FileSize trunca o tamanho do arquivo como 0.

[in, optional] FileIdentity

FileIdentity é um buffer de modo de usuário que contém as informações opacas de arquivo ou diretório fornecidas pelo chamador. O blob FileIdentity não deve exceder 4 KB de tamanho. FileIdentity é passado de volta para o provedor de sincronização em todos os retornos de chamada. Isso é opcional se uma atualização não for necessária ou se o chamador quiser remover o blob FileIdentity do espaço reservado a ser atualizado.

[in] FileIdentityLength

Comprimento, em bytes, da FileIdentity.

[in, optional] DehydrateRangeArray

Essa matriz especifica intervalos do espaço reservado existente que não serão mais considerados válidos após a atualização.

O uso mais simples desse parâmetro é passar um único intervalo, informando à plataforma que todo o intervalo de bytes de dados agora é inválido. Um uso mais complexo desse parâmetro é fornecer uma série de intervalos discretos a serem considerados inválidos. Isso implica que o provedor de sincronização pode distinguir as alterações em um nível de sub-arquivo. Todos os deslocamentos e comprimentos devem ser PAGE_SIZE Alinhados. A plataforma garantirá que todos os intervalos especificados sejam desidratados como parte da atualização. Se a desidratação de qualquer intervalo falhar, a API falhará em vez de resultar em conteúdo de arquivo rasgado.

Observação

Passar um único intervalo com Deslocamento 0 e Comprimento CF_EOF invalidará todo o arquivo – isso tem o mesmo efeito que passar o sinalizador CF_UPDATE_FLAG_DEHYDRATE . Além disso, passar CF_UPDATE_FLAG_DEHYDRATE faz com que DehydrateRangeArray seja removido silenciosamente

[in] DehydrateRangeCount

A contagem de uma série de partições discretas de DehydrateRangeArray de dados de espaço reservado.

[in] UpdateFlags

Atualize sinalizadores para espaços reservados. UpdateFlags pode ser definido com os seguintes valores:

Sinalizador	Descrição
CF_UPDATE_FLAG_VERIFY_IN_SYNC	A atualização falhará se o atributo IN_SYNC não estiver definido no momento no espaço reservado. Isso é para impedir que uma corrida entre a sincronização de alterações da nuvem para um espaço reservado local e o fluxo de dados do espaço reservado seja modificado localmente.
CF_UPDATE_FLAG_MARK_IN_SYNC	A plataforma marca o espaço reservado como em sincronia após uma operação de espaço reservado de atualização bem-sucedida.
CF_UPDATE_FLAG_DEHYDRATE	Aplicável somente para arquivos. Quando especificado, a plataforma desidrata o arquivo depois de atualizar o 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_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION	Aplicável somente para diretórios. Quando especificado, ele marca o diretório de espaço reservado atualizado 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_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION	Aplicável somente para diretórios. Quando especificado, ele marca o diretório de espaço reservado atualizado totalmente preenchido de modo que qualquer acesso futuro a ele seja tratado pela plataforma sem nenhum retorno de chamada para o provedor de sincronização.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY	FileIdentity e FileIdentityLength são ignorados e a plataforma removerá o blob de identidade de arquivo existente no espaço reservado após uma chamada de atualização bem-sucedida.
CF_UPDATE_FLAG_CLEAR_IN_SYNC	A plataforma marca o espaço reservado como não sincronizado em uma operação de espaço reservado de atualização bem-sucedida.
CF_UPDATE_FLAG_REMOVE_PROPERTY	A plataforma remove todas as propriedades extrínsecas existentes no espaço reservado.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA	A plataforma passa CF_FS_METADATA para o sistema de arquivos sem nenhuma filtragem; caso contrário, a plataforma ignora a configuração de todos os campos cujo valor é 0.
CF_UPDATE_FLAG_ALWAYS_FULL	Efetiva somente em arquivos de espaço reservado. Quando especificado, o espaço reservado a ser atualizado é marcado como sempre cheio. Depois de hidratado, qualquer tentativa de desidratar esse arquivo de espaço reservado falhará com o código de erro ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_UPDATE_FLAG_ALLOW_PARTIAL	Efetiva somente em arquivos de espaço reservado. Quando especificado, o estado sempre completo em um arquivo de espaço reservado, se presente, é limpo, permitindo que ele seja desidratado novamente. É inválido especificar esse sinalizador junto com CF_UPDATE_FLAG_ALWAYS_FULL e ERROR_CLOUD_FILE_INVALID_REQUEST de código de erro serão retornados como resultado.

[in, out, optional] UpdateUsn

Na entrada, UpdateUsn instrui a plataforma a executar a atualização somente se o arquivo ainda tiver o mesmo valor de USN que o passado. Isso serve a uma finalidade semelhante à CF_UPDATE_FLAG_VERIFY_IN_SYNC , mas também abrange alterações de metadados locais. Passar um ponteiro para um valor USN de 0 na entrada é o mesmo que passar um NULL ponteiro.

No retorno, UpdateUsn recebe o valor final de USN depois que as ações de atualização foram executadas.

[in, out, optional] Overlapped

Quando especificado e combinado com um FileHandle assíncrono, Overlapped permite que a plataforma execute a chamada cfUpdatePlaceholder 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

Para atualizar um espaço reservado:

• O espaço reservado a ser atualizado 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 falhará 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 falhará com HRESULT(ERROR_CLOUD_FILE_PINNED).
• Se a desidratação for solicitada, o espaço reservado deverá estar sincronizado ou a chamada falhará com HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
• O chamador deve ter WRITE_DATA ou WRITE_DAC acesso ao espaço reservado a ser atualizado. 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

CF_UPDATE_FLAGS