Funzione BackupRead (winbase.h)
La funzione BackupRead può essere usata per eseguire il backup di un file o una directory, incluse le informazioni di sicurezza. La funzione legge i dati associati a un file o una directory specificati in un buffer, che può quindi essere scritto nel supporto di backup usando la funzione WriteFile .
Sintassi
BOOL BackupRead(
[in] HANDLE hFile,
[out] LPBYTE lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[out] LPDWORD lpNumberOfBytesRead,
[in] BOOL bAbort,
[in] BOOL bProcessSecurity,
[out] LPVOID *lpContext
);
Parametri
[in] hFile
Gestire il file o la directory da eseguire il backup. Per ottenere l'handle, chiamare la funzione CreateFile . Le sacls non vengono lette a meno che l'handle di file non sia stato creato con il diritto di accesso ACCESS_SYSTEM_SECURITY . Per altre informazioni, vedere Sicurezza file e diritti di accesso.
L'handle deve essere sincrono (non sovrapposto). Ciò significa che il flag di FILE_FLAG_OVERLAPPED non deve essere impostato quando viene chiamato CreateFile . Questa funzione non convalida che l'handle che riceve è sincrono, quindi 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 BackupRead 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.
[out] lpBuffer
Puntatore a un buffer che riceve i dati.
[in] nNumberOfBytesToRead
Lunghezza del buffer, in byte. Le dimensioni del buffer devono essere maggiori delle dimensioni di una struttura WIN32_STREAM_ID .
[out] lpNumberOfBytesRead
Puntatore a una variabile che riceve il numero di byte letti.
Se la funzione restituisce un valore diverso da zero e la variabile a cui punta per lpNumberOfBytesRead è zero, tutti i dati associati all'handle di file sono stati letti.
[in] bAbort
Indica se è stato completato l'uso di BackupRead nell'handle. Durante il backup del file, specificare questo parametro come FALSE. Dopo aver eseguito l'uso di BackupRead, è necessario chiamare BackupRead una volta più volte specificando TRUE per questo parametro e passando il lpContext appropriato. lpContext deve essere passato quando bAbort è TRUE; tutti gli altri parametri vengono ignorati.
[in] bProcessSecurity
Indica se la funzione ripristina i dati dell'elenco di controllo di accesso (ACL) per il file o la directory.
Se bProcessSecurity è TRUE, i dati ACL verranno sottoposti a backup.
[out] lpContext
Puntatore a una variabile che riceve un puntatore a una struttura di dati interna usata da BackupRead per mantenere le informazioni di contesto durante un'operazione di backup.
È necessario impostare la variabile puntata su lpContext su NULL prima della prima chiamata a BackupRead per il file o la directory specificata. La funzione alloca la memoria per la struttura dei dati e quindi imposta la variabile per puntare a tale struttura. Non è necessario modificare lpContext o la variabile a cui punta tra le chiamate a BackupRead.
Per rilasciare la memoria usata dalla struttura di dati, chiamare BackupRead con il parametro bAbort impostato su TRUE al termine dell'operazione di backup.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero, che indica che si è verificato un errore di I/O. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Questa funzione non è destinata all'uso nel backup di file crittografati nel file system crittografato. Usare ReadEncryptedFileRaw per tale scopo.
Se si verifica un errore durante la lettura dei dati di BackupRead , il processo chiamante può ignorare i dati non valido chiamando la funzione BackupSeek .
Il file o la directory devono essere ripristinati usando la funzione BackupWrite .
Requisiti
| 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 |