BackupRead-Funktion (winbase.h)
Die BackupRead-Funktion kann verwendet werden, um eine Datei oder ein Verzeichnis zu sichern, einschließlich der Sicherheitsinformationen. Die Funktion liest Daten, die einer angegebenen Datei oder einem angegebenen Verzeichnis zugeordnet sind, in einen Puffer, der dann mithilfe der WriteFile-Funktion auf das Sicherungsmedium geschrieben werden kann.
Syntax
BOOL BackupRead(
[in] HANDLE hFile,
[out] LPBYTE lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[out] LPDWORD lpNumberOfBytesRead,
[in] BOOL bAbort,
[in] BOOL bProcessSecurity,
[out] LPVOID *lpContext
);
Parameter
[in] hFile
Handle für die zu sichernde Datei oder das Verzeichnis. Rufen Sie die CreateFile-Funktion auf, um das Handle abzurufen. Die SACLs werden nur gelesen, wenn das Dateihandle mit dem zugriffsrecht ACCESS_SYSTEM_SECURITY erstellt wurde. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.
Das Handle muss synchron (nicht überlappend) sein. Dies bedeutet, dass das FILE_FLAG_OVERLAPPED-Flag nicht festgelegt werden darf, wenn CreateFile aufgerufen wird. Diese Funktion überprüft nicht, ob das empfangene Handle synchron ist, sodass sie keinen Fehlercode für ein synchrones Handle zurückgibt, aber der Aufruf mit einem asynchronen (überlappenden) Handle kann zu geringfügigen Fehlern führen, die sehr schwierig zu debuggen sind.
Die BackupRead-Funktion schlägt möglicherweise fehl, wenn CreateFile mit dem Flag FILE_FLAG_NO_BUFFERING aufgerufen wurde. In diesem Fall gibt die GetLastError-Funktion den Wert ERROR_INVALID_PARAMETER zurück.
[out] lpBuffer
Zeiger auf einen Puffer, der die Daten empfängt.
[in] nNumberOfBytesToRead
Länge des Puffers in Bytes. Die Puffergröße muss größer als die Größe einer WIN32_STREAM_ID-Struktur sein.
[out] lpNumberOfBytesRead
Zeiger auf eine Variable, die die Anzahl der gelesenen Bytes empfängt.
Wenn die Funktion einen Wert ungleich null zurückgibt und die Variable, auf die von lpNumberOfBytesRead verwiesen wird, null ist, wurden alle dem Dateihandle zugeordneten Daten gelesen.
[in] bAbort
Gibt an, ob Sie die Verwendung von BackupRead auf dem Handle abgeschlossen haben. Geben Sie während der Sicherung der Datei diesen Parameter als FALSE an. Sobald Sie die Verwendung von BackupRead abgeschlossen haben, müssen Sie BackupRead erneut aufrufen, indem Sie TRUE für diesen Parameter angeben und den entsprechenden lpContext übergeben. lpContext muss übergeben werden, wenn bAbortauf TRUE festgelegt ist; alle anderen Parameter werden ignoriert.
[in] bProcessSecurity
Gibt an, ob die Funktion die ACL-Daten (Access Control List, Zugriffssteuerungsliste) für die Datei oder das Verzeichnis wiederhergestellt.
Wenn bProcessSecurityauf TRUE festgelegt ist, werden die ACL-Daten gesichert.
[out] lpContext
Zeiger auf eine Variable, die einen Zeiger auf eine interne Datenstruktur empfängt, die von BackupRead zum Verwalten von Kontextinformationen während eines Sicherungsvorgangs verwendet wird.
Sie müssen die Variable, auf die lpContext verweist, vor dem ersten Aufruf von BackupRead für die angegebene Datei oder das angegebene Verzeichnis auf NULL festlegen. Die Funktion ordnet Arbeitsspeicher für die Datenstruktur zu und legt dann die Variable so fest, dass sie auf diese Struktur verweist. Sie dürfen lpContext oder die Variable, auf die zwischen Aufrufen von BackupRead verweist, nicht ändern.
Um den von der Datenstruktur verwendeten Arbeitsspeicher freizugeben, rufen Sie BackupRead auf, wobei der bAbort-Parameter auf TRUE festgelegt ist, wenn der Sicherungsvorgang abgeschlossen ist.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null, was angibt, dass ein E/A-Fehler aufgetreten ist. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Diese Funktion ist nicht für die Sicherung von Dateien vorgesehen, die unter dem verschlüsselten Dateisystem verschlüsselt sind. Verwenden Sie zu diesem Zweck ReadEncryptedFileRaw .
Wenn ein Fehler auftritt, während BackupRead Daten liest, kann der aufrufende Prozess die fehlerhaften Daten überspringen, indem die BackupSeek-Funktion aufgerufen wird.
Die Datei oder das Verzeichnis sollte mithilfe der BackupWrite-Funktion wiederhergestellt werden.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbase.h (Windows.h einschließen) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |