Função BackupRead (winbase.h)

A função BackupRead pode ser usada para fazer backup de um arquivo ou diretório, incluindo as informações de segurança. A função lê dados associados a um arquivo ou diretório especificado em um buffer, que pode ser gravado no meio de backup usando a função WriteFile .

Sintaxe

BOOL BackupRead(
  [in]  HANDLE  hFile,
  [out] LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToRead,
  [out] LPDWORD lpNumberOfBytesRead,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Parâmetros

[in] hFile

Manipule para o arquivo ou diretório a ser feito backup. Para obter o identificador, chame a função CreateFile . As SACLs não são lidas, a menos que o identificador de arquivo tenha sido criado com o direito de acesso ACCESS_SYSTEM_SECURITY . Para obter mais informações, consulte Direitos de segurança e acesso de arquivos.

O identificador deve ser síncrono (não sobreposto). Isso significa que o sinalizador FILE_FLAG_OVERLAPPED não deve ser definido quando CreateFile é chamado. Essa função não valida se o identificador que recebe é síncrono, portanto, não retorna um código de erro para um identificador síncrono, mas chamá-lo com um identificador assíncrono (sobreposto) pode resultar em erros sutis que são muito difíceis de depurar.

A função BackupRead poderá falhar se CreateFile tiver sido chamado com o sinalizador FILE_FLAG_NO_BUFFERING. Nesse caso, a função GetLastError retorna o valor ERROR_INVALID_PARAMETER.

[out] lpBuffer

Ponteiro para um buffer que recebe os dados.

[in] nNumberOfBytesToRead

Comprimento do buffer, em bytes. O tamanho do buffer deve ser maior que o tamanho de uma estrutura de WIN32_STREAM_ID .

[out] lpNumberOfBytesRead

Ponteiro para uma variável que recebe o número de bytes lidos.

Se a função retornar um valor diferente de zero e a variável apontada por lpNumberOfBytesRead for zero, todos os dados associados ao identificador de arquivo serão lidos.

[in] bAbort

Indica se você terminou de usar BackupRead no identificador. Enquanto estiver fazendo backup do arquivo, especifique esse parâmetro como FALSE. Depois de terminar de usar o BackupRead, você deverá chamar BackupRead mais uma vez especificando TRUE para esse parâmetro e passando o lpContext apropriado. lpContext deve ser passado quando bAbort é TRUE; todos os outros parâmetros são ignorados.

[in] bProcessSecurity

Indica se a função restaurará os dados da ACL (lista de controle de acesso) para o arquivo ou diretório.

Se bProcessSecurity for TRUE, os dados de ACL serão copiados em backup.

[out] lpContext

Ponteiro para uma variável que recebe um ponteiro para uma estrutura de dados interna usada pelo BackupRead para manter informações de contexto durante uma operação de backup.

Você deve definir a variável apontada por lpContext como NULL antes da primeira chamada para BackupRead para o arquivo ou diretório especificado. A função aloca memória para a estrutura de dados e define a variável para apontar para essa estrutura. Você não deve alterar lpContext ou a variável para a qual ele aponta entre chamadas para BackupRead.

Para liberar a memória usada pela estrutura de dados, chame BackupRead com o parâmetro bAbort definido como TRUE quando a operação de backup for concluída.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero, indicando que ocorreu um erro de E/S. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Essa função não se destina ao uso no backup de arquivos criptografados no Sistema de Arquivos Criptografados. Use ReadEncryptedFileRaw para essa finalidade.

Se ocorrer um erro enquanto BackupRead estiver lendo dados, o processo de chamada poderá ignorar os dados incorretos chamando a função BackupSeek .

O arquivo ou diretório deve ser restaurado usando a função BackupWrite .

Requisitos

Confira também

BackupSeek

BackupWrite

Criando um aplicativo de backup

ReadEncryptedFileRaw

WIN32_STREAM_ID