Função BackupWrite (winbase.h)

  • Artigo

A função BackupWrite pode ser usada para restaurar um arquivo ou diretório cujo backup foi feito usando BackupRead. Use a função ReadFile para obter um fluxo de dados do meio de backup e, em seguida, use BackupWrite para gravar os dados no arquivo ou diretório especificado.

Sintaxe

BOOL BackupWrite(
  [in]  HANDLE  hFile,
  [in]  LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToWrite,
  [out] LPDWORD lpNumberOfBytesWritten,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Parâmetros

[in] hFile

Manipule para o arquivo ou diretório a ser restaurado. Para obter o identificador, chame a função CreateFile . As SACLs não são restauradas, a menos que o identificador de arquivo tenha sido criado com o direito de acesso ACCESS_SYSTEM_SECURITY . Para garantir que as ACEs de integridade sejam restauradas corretamente, o identificador de arquivo também deve ter sido criado com o direito de acesso WRITE_OWNER . Para obter mais informações, consulte Segurança de arquivo e direitos de acesso.

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 que o identificador recebido é 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 BackupWrite 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.

[in] lpBuffer

Ponteiro para um buffer do qual a função grava dados.

[in] nNumberOfBytesToWrite

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

[out] lpNumberOfBytesWritten

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

[in] bAbort

Indica se você terminou de usar BackupWrite no identificador. Enquanto você estiver restaurando o arquivo, especifique esse parâmetro como FALSE. Depois de terminar de usar BackupWrite, você deve chamar BackupWrite 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

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

Se bProcessSecurity for TRUE, você precisará especificar WRITE_OWNER e WRITE_DAC acesso ao abrir o identificador de arquivo ou diretório. Se o identificador não tiver esses direitos de acesso, o sistema operacional negará acesso aos dados da ACL e a restauração de dados da ACL não ocorrerá.

[out] lpContext

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

Você deve definir a variável apontada por lpContext como NULL antes da primeira chamada para BackupWrite 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 BackupWrite.

Para liberar a memória usada pela estrutura de dados, chame BackupWrite com o parâmetro bAbort definido como TRUE quando a operação de restauração 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 na restauração de arquivos criptografados no Sistema de Arquivos Criptografados. Use WriteEncryptedFileRaw para essa finalidade.

Os dados lidos do meio de backup devem ser subfluxos separados por estruturas WIN32_STREAM_ID .

O tipo de fluxo BACKUP_LINK permite restaurar arquivos com links físicos.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [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 winbase.h (incluir Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

BackupRead

BackupSeek

CreateFile

WIN32_STREAM_ID

WriteEncryptedFileRaw