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

Vedere anche

BackupSeek

BackupWrite

Creazione di un'applicazione di backup

ReadEncryptedFileRaw

WIN32_STREAM_ID