Funzione BackupWrite (winbase.h)

Articolo
03/13/2024

La funzione BackupWrite può essere usata per ripristinare un file o una directory di cui è stato eseguito il backup usando BackupRead. Usare la funzione ReadFile per ottenere un flusso di dati dal supporto di backup, quindi usare BackupWrite per scrivere i dati nel file o nella directory specificata.

Sintassi

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

Parametri

[in] hFile

Gestire il file o la directory da ripristinare. Per ottenere l'handle, chiamare la funzione CreateFile . Gli elenchi SACL non vengono ripristinati a meno che l'handle di file non sia stato creato con il diritto di accesso ACCESS_SYSTEM_SECURITY . Per garantire che gli ACL di integrità vengano ripristinati correttamente, l'handle di file deve essere stato creato anche con il diritto di accesso WRITE_OWNER . Per altre informazioni, vedere Protezione dei file e diritti di accesso.

L'handle deve essere sincrono (non sovrapposto). Ciò significa che il flag FILE_FLAG_OVERLAPPED non deve essere impostato quando viene chiamato CreateFile . Questa funzione non convalida che l'handle ricevuto sia sincrono, pertanto non restituisce un codice di errore per un handle sincrono, ma chiamandolo con un handle asincrono (sovrapposto) può causare errori sottili che sono molto difficili da eseguire per il debug.

La funzione BackupWrite potrebbe non riuscire se CreateFile è stato chiamato con il flag FILE_FLAG_NO_BUFFERING. In questo caso, la funzione GetLastError restituisce il valore ERROR_INVALID_PARAMETER.

[in] lpBuffer

Puntatore a un buffer da cui la funzione scrive i dati.

[in] nNumberOfBytesToWrite

Dimensioni del buffer, in byte. Le dimensioni del buffer devono essere maggiori delle dimensioni di una struttura WIN32_STREAM_ID .

[out] lpNumberOfBytesWritten

Puntatore a una variabile che riceve il numero di byte scritti.

[in] bAbort

Indica se è stato completato l'uso di BackupWrite nell'handle. Durante il ripristino del file, specificare questo parametro come FALSE. Al termine dell'uso di BackupWrite, è necessario chiamare BackupWrite una volta di più specificando TRUE per questo parametro e passando il valore lpContext appropriato. lpContext deve essere passato quando bAbort è TRUE; tutti gli altri parametri vengono ignorati.

[in] bProcessSecurity

Specifica se la funzione ripristina i dati dell'elenco di controllo di accesso (ACL) per il file o la directory.

Se bProcessSecurity è TRUE, è necessario specificare WRITE_OWNER e WRITE_DAC l'accesso all'apertura del file o dell'handle di directory. Se l'handle non dispone di tali diritti di accesso, il sistema operativo nega l'accesso ai dati ACL e il ripristino dei dati ACL non verrà eseguito.

[out] lpContext

Puntatore a una variabile che riceve un puntatore a una struttura di dati interna usata da BackupWrite per mantenere le informazioni di contesto durante un'operazione di ripristino.

È necessario impostare la variabile a cui punta lpContext su NULL prima della prima chiamata a BackupWrite per il file o la directory specificata. La funzione alloca la memoria per la struttura dei dati e quindi imposta la variabile in modo che punti a tale struttura. Non è necessario modificare lpContext o la variabile a cui punta tra le chiamate a BackupWrite.

Per rilasciare la memoria usata dalla struttura dei dati, chiamare BackupWrite con il parametro bAbort impostato su TRUE al termine dell'operazione di ripristino.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero, a indicare che si è verificato un errore di I/O. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Questa funzione non è destinata all'uso nel ripristino di file crittografati nel file system crittografato. Usare WriteEncryptedFileRaw a tale scopo.

I dati letti dal supporto di backup devono essere sottostream separati da strutture WIN32_STREAM_ID .

Il tipo di flusso BACKUP_LINK consente di ripristinare i file con collegamenti reali.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll