Método IVssComponent::GetDifferencedFile (vswriter.h)

  • Artigo

O método GetDifferencedFile retorna informações sobre um conjunto de arquivos (um arquivo ou arquivos especificado) para participar de um backup ou restauração incremental ou diferencial como um arquivo diferente, ou seja, backup e restaurações associados a ele devem ser implementados como se arquivos inteiros fossem copiados de e para a mídia de backup (em vez de usar arquivos parciais).

Esse método pode ser chamado por um solicitante ou um gravador durante operações de backup ou restauração.

Sintaxe

HRESULT GetDifferencedFile(
  [in]  UINT     iDifferencedFile,
  [out] BSTR     *pbstrPath,
  [out] BSTR     *pbstrFilespec,
  [out] BOOL     *pbRecursive,
  [out] BSTR     *pbstrLsnString,
  [out] FILETIME *pftLastModifyTime
);

Parâmetros

[in] iDifferencedFile

Número de índice do arquivo diferenciado a ser examinado. O valor desse parâmetro é um inteiro de 0 a n–1 inclusive, em que n é o número total de arquivos diferenciados associados a um determinado componente (e seus subcomponentes se ele definir um conjunto de componentes). O valor de n é retornado por IVssComponent::GetDifferencedFilesCount.

[out] pbstrPath

O endereço de uma variável alocada pelo chamador que recebe uma cadeia de caracteres que contém o caminho para os arquivos diferenciados.

Os usuários desse método precisam marcar para determinar se esse caminho termina com uma barra invertida (\).

[out] pbstrFilespec

O endereço de uma variável alocada pelo chamador que recebe uma cadeia de caracteres que contém a especificação de arquivo dos arquivos diferenciados.

[out] pbRecursive

O endereço de uma variável alocada pelo chamador que recebe um booliano especificando se a especificação de arquivo para os arquivos diferenciados deve ser interpretada recursivamente. Se TRUE, toda a hierarquia de diretórios precisará ser pesquisada em busca de arquivos que correspondam à especificação de arquivo pbstrFilespec para localizar arquivos a serem tratados como arquivos diferenciados durante backups incrementais ou diferenciais. Se FALSE, somente o diretório raiz precisará ser pesquisado.

[out] pbstrLsnString

Reservado para uso futuro.

[out] pftLastModifyTime

O endereço de uma variável alocada pelo chamador que recebe a especificação do gravador da hora da última modificação para os arquivos de diferença, expresso como uma estrutura FILETIME .

Retornar valor

Veja a seguir os códigos de retorno válidos para esse método.

Valor Significado
S_OK
 Retornou com êxito o valor do atributo.
E_INVALIDARG
 Um dos valores de parâmetro não é válido.
E_OUTOFMEMORY
 O chamador está sem memória ou outros recursos do sistema.
VSS_E_OBJECT_NOT_FOUND
 Nenhum arquivo diferente correspondente ao índice fornecido foi encontrado.
VSS_E_INVALID_XML_DOCUMENT
 O documento XML não é válido. Verifique o log de eventos para obter detalhes. Para obter mais informações, consulte Tratamento de eventos e erros no VSS.

Comentários

GetDifferencedFile pode ser chamado por um solicitante ou um gravador durante operações de backup ou restauração.

Se a chamada para GetDifferencedFile for bem-sucedida, o chamador será responsável por liberar a cadeia de caracteres retornada nos parâmetros pbstrPath e pbstrFilespec chamando a função SysFreeString .

Como gravadores podem indicar arquivos diferenciados com chamadas para IVssComponent::AddDifferencedFilesByLastModifyTime a qualquer momento antes do backup real de arquivos, normalmente, durante o tratamento de um evento PostSnapshot (CVssWriter::OnPostSnapshot), durante backups GetDifferencedFile não é útilmente chamado antes do retorno de IVssBackupComponents::D oSnapshotSet retornou com êxito.

O carimbo de data/hora retornado por GetDifferencedFile se aplica a todos os arquivos que correspondem ao caminho retornado (pbstrPath) e à especificação de arquivo (pbstrFilespec).

Se o valor de carimbo de data/hora retornado por GetDifferencedFile (pftLastModifyTime) for diferente de zero, um solicitante deverá respeitar esse valor independentemente de seus próprios registros e informações do sistema de arquivos e usá-lo para determinar se o arquivo diferenciado deve ser incluído em um backup diferencial ou incremental.

Se o carimbo de data/hora retornado por GetDifferencedFile for zero, o solicitante poderá usar informações do sistema de arquivos e seus próprios registros para determinar se os arquivos diferenciados devem ser incluídos em um backup diferencial ou incremental.

Os arquivos diferenciados podem ser um dos seguintes:

Ao fazer referência a um conjunto de arquivos que já faz parte do componente, a combinação de caminho, especificação de arquivo e sinalizador de recursão (wszPath, wszFileSpec e bRecursive, respectivamente) usado ao chamar GetDifferencedFile deve corresponder ao de um conjunto de arquivos já no componente ou de um de seus subcomponentes (se o componente definir um conjunto de componentes).

Quando GetDifferencedFile retorna um novo arquivo diferente, o caminho desse arquivo (pbstrPath) deve corresponder ou estar abaixo de um caminho já no componente ou de um de seus subcomponentes (se o componente definir um conjunto de componentes).

Além disso, os arquivos retornados por GetDifferencedFile ainda não devem ser gerenciados por componente ou gravador.

Se qualquer um desses critérios for violado, eles constituirão um erro por parte do gravador e deverão ser relatados.

Não há nenhum método na interface IVssComponent que permita alterar ou adicionar um mapeamento de local alternativo para novos arquivos retornados por GetDifferencedFilesByLastModifyTime. Se um mapeamento de local alternativo corresponder ao novo arquivo, esse local alternativo será usado.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho vswriter.h (inclua Vss.h, VsWriter.h)
Biblioteca VssApi.lib

Confira também

IVssComponent

IVssComponent::AddDifferencedFilesByLastModifyTime

IVssComponent::GetDifferencedFilesCount

Backups incrementais e diferenciais