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

Siehe auch

BackupSeek

BackupWrite

Erstellen einer Sicherungsanwendung

ReadEncryptedFileRaw

WIN32_STREAM_ID