Funzione BackupWrite (winbase.h)
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 |