Função PrjUpdateFileIfNeeded (projectedfslib.h)

Permite que um provedor atualize um item que foi armazenado em cache no sistema de arquivos local.

Sintaxe

HRESULT PrjUpdateFileIfNeeded(
  [in]            PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
  [in]            PCWSTR                               destinationFileName,
  [in]            const PRJ_PLACEHOLDER_INFO           *placeholderInfo,
  [in]            UINT32                               placeholderInfoSize,
  [in, optional]  PRJ_UPDATE_TYPES                     updateFlags,
  [out, optional] PRJ_UPDATE_FAILURE_CAUSES            *failureReason
);

Parâmetros

[in] namespaceVirtualizationContext

Identificador opaco para a instância de virtualização.

[in] destinationFileName

Uma cadeia de caracteres Unicode terminada em nulo especificando o caminho, em relação à raiz de virtualização, para o arquivo ou diretório a ser atualizado.

[in] placeholderInfo

Um ponteiro para um buffer de PRJ_PLACEHOLDER_INFO que contém os metadados atualizados para o arquivo ou diretório.

Se placeholderInfo-VersionInfo.ContentID> contiver um identificador de conteúdo igual ao identificador de conteúdo já no arquivo/diretório, a chamada será bem-sucedida e nenhuma atualização ocorrerá. Caso contrário, se a chamada for bem-sucedida, o placeholderInfo-VersionInfo.ContentID> substituirá o identificador de conteúdo existente no arquivo.

[in] placeholderInfoSize

O tamanho em bytes do buffer apontado por placeholderInfo.

[in, optional] updateFlags

Sinalizadores para controlar atualizações.

Se o item for um espaço reservado sujo, um arquivo completo ou uma pedra de tombamento e o provedor não especificar os sinalizadores apropriados, essa rotina não atualizará o espaço reservado

[out, optional] failureReason

Ponteiro opcional para receber um código que descreve o motivo da falha de uma atualização.

Valor de retorno

Se um erro HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION) for retornado, a atualização falhará devido ao estado do item e ao valor de updateFlags. failureReason, se especificado, descreverá o motivo da falha.

Observações

O provedor usa essa rotina para atualizar um item no sistema de arquivos local se as informações do item foram alteradas no repositório de backup do provedor e as atualizações devem ser refletidas nos itens armazenados em cache no sistema de arquivos local.

Essa rotina não pode ser chamada em um arquivo/diretório virtual. Se o arquivo/diretório a ser atualizado estiver em qualquer estado diferente de "espaço reservado", o provedor deverá especificar uma combinação apropriada de valores PRJ_UPDATE_TYPES no parâmetro updateFlags. Isso ajuda a proteger contra perda acidental de dados, pois após o retorno bem-sucedido dessa rotina, o item se torna um espaço reservado com os metadados atualizados; todos os metadados que foram alterados desde que o espaço reservado foi criado ou todos os dados de arquivo contidos são descartados.

O provedor usa o sistema de arquivos local como um cache dos itens que gerencia. Um item (arquivo ou diretório) pode estar em um dos seis estados no sistema de arquivos local.

Virtual – o item não existe localmente no disco. Ele é projetado, ou seja, sintetizado durante enumerações de seu diretório pai. Os itens virtuais são mesclados com todos os itens que podem existir no disco para apresentar o conteúdo completo do diretório pai.

Espaço reservado – Para arquivos: o conteúdo do arquivo (fluxo de dados primário) não está presente no disco. Os metadados do arquivo (nome, tamanho, carimbos de data/hora, atributos etc.) são armazenados em cache no disco. Para diretórios: Alguns ou todos os descendentes imediatos do diretório (os arquivos e diretórios no diretório) não estão presentes no disco, ou seja, eles ainda são virtuais. Os metadados do diretório (nome, carimbos de data/hora, atributos etc.) são armazenados em cache no disco.

Espaço reservado hidratado – Para arquivos: o conteúdo e os metadados do arquivo foram armazenados em cache no disco. Também chamado de "arquivo parcial". Para diretórios: os diretórios nunca são espaços reservados hidratados. Um diretório criado no disco como um espaço reservado nunca se torna um diretório de espaço reservado hidratado. Isso permite que o provedor adicione ou remova itens do diretório em seu repositório de backup e faça com que essas alterações sejam refletidas no cache local.

Espaço reservado sujo (hidratado ou não) – os metadados do item foram modificados localmente e não são mais um cache de seu estado no repositório do provedor. Observe que a criação ou exclusão de um arquivo ou diretório em um diretório de espaço reservado faz com que esse diretório de espaço reservado fique sujo.

Arquivo/diretório completo – Para arquivos: o conteúdo do arquivo (fluxo de dados primário) foi modificado. O arquivo não é mais um cache de seu estado no repositório do provedor. Os arquivos que foram criados no sistema de arquivos local (ou seja, que não existem no repositório do provedor) também são considerados arquivos completos. Para diretórios: os diretórios criados no sistema de arquivos local (ou seja, que não existem no repositório do provedor) são considerados diretórios completos. Um diretório criado no disco como um espaço reservado nunca se torna um diretório completo.

Tombstone - Um espaço reservado oculto especial que representa um item que foi excluído do sistema de arquivos local. Quando um diretório é enumerado, o ProjFS mescla o conjunto de itens locais (espaços reservados, arquivos completos etc.) com o conjunto de itens projetados virtuais. Se um item aparecer nos conjuntos locais e projetados, o item local terá precedência. Se um arquivo não existir, não haverá nenhum estado local, portanto, ele aparecerá na enumeração. No entanto, se esse item tivesse sido excluído, tê-lo exibido na enumeração seria inesperado. Substituir um item excluído por uma pedra de tombamento resulta nos seguintes efeitos:

• Enumerações para não revelar o item
• O arquivo é aberto que espera que o item exista com falha, por exemplo, "arquivo não encontrado".
• O arquivo cria que espera ter êxito somente se o item não existir com êxito; O ProjFS remove a pedra tombária como parte da operação.

Para ilustrar os estados acima, considere a seguinte sequência, considerando um provedor ProjFS que tem um único arquivo "foo.txt" localizado na raiz de virtualização C:\root.

• Um aplicativo enumera C:\root. Ele vê o arquivo virtual"foo.txt". Como o arquivo ainda não foi acessado, o arquivo não existe no disco.
• O aplicativo abre um identificador para C:\root\foo.txt. O ProjFS informa ao provedor para criar um espaço reservado para ele.
• O aplicativo lê o conteúdo do arquivo. O provedor fornece o conteúdo do arquivo para o ProjFS e é armazenado em cache para C:\root\foo.txt. O arquivo agora é um espaço reservado hidratado.
• O aplicativo atualiza o carimbo de data/hora última modificação. O arquivo agora é um espaço reservado hidratado sujo.
• O aplicativo abre um identificador para o acesso de gravação ao arquivo. C:\root\foo.txt agora é um arquivo completo.
• O aplicativo exclui C:\root\foo.txt. O ProjFS substitui o arquivo por uma pedra de tombamento. Agora, quando o aplicativo enumera C:\root it does not see foo.txt. Se ele tentar abrir o arquivo, a abertura falhará com ERROR_FILE_NOT_FOUND.

Requirements