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.

[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:

[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

Confira também

CfOpenFileWithOplock

CF_UPDATE_FLAGS