BackupWrite-Funktion (winbase.h)

Artikel
08/27/2023

Die BackupWrite-Funktion kann verwendet werden, um eine Datei oder ein Verzeichnis wiederherzustellen, die mit BackupRead gesichert wurde. Verwenden Sie die ReadFile-Funktion , um einen Datenstrom vom Sicherungsmedium abzurufen. Verwenden Sie dann BackupWrite , um die Daten in die angegebene Datei oder das angegebene Verzeichnis zu schreiben.

Syntax

BOOL BackupWrite(
  [in]  HANDLE  hFile,
  [in]  LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToWrite,
  [out] LPDWORD lpNumberOfBytesWritten,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Parameter

[in] hFile

Behandeln Sie die wiederherzustellende Datei oder das Verzeichnis. Um das Handle abzurufen, rufen Sie die CreateFile-Funktion auf. Die SACLs werden erst wiederhergestellt, wenn das Dateihandle mit dem ACCESS_SYSTEM_SECURITY Zugriffsrecht erstellt wurde. Um sicherzustellen, dass die Integritäts-ACEs ordnungsgemäß wiederhergestellt werden, muss auch das Dateihandle mit dem WRITE_OWNER-Zugriffsrecht erstellt worden sein. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.

Das Handle muss synchron (nicht überlappt) 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 kein Fehlercode für ein synchrones Handle zurückgegeben wird, aber das Aufrufen mit einem asynchronen (überlappenden) Handle kann zu subtilen Fehlern führen, die sehr schwierig zu debuggen sind.

Die BackupWrite-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.

[in] lpBuffer

Zeiger auf einen Puffer, aus dem die Funktion Daten schreibt.

[in] nNumberOfBytesToWrite

Größe des Puffers in Bytes. Die Puffergröße muss größer als die Größe einer WIN32_STREAM_ID-Struktur sein.

[out] lpNumberOfBytesWritten

Zeiger auf eine Variable, die die Anzahl der geschriebenen Bytes empfängt.

[in] bAbort

Gibt an, ob Sie die Verwendung von BackupWrite für das Handle abgeschlossen haben. Geben Sie während der Wiederherstellung der Datei diesen Parameter als FALSE an. Nachdem Sie BackupWrite verwendet haben, müssen Sie BackupWrite noch einmal aufrufen, indem Sie true für diesen Parameter angeben und den entsprechenden lpContext übergeben. lpContext muss übergeben werden, wenn bAborttrue ist; alle anderen Parameter werden ignoriert.

[in] bProcessSecurity

Gibt an, ob die Funktion die Zugriffssteuerungslistendaten (Access-Control List, ACL) für die Datei oder das Verzeichnis wiederherstellen soll.

Wenn bProcessSecurityTRUE ist, müssen Sie beim Öffnen des Datei- oder Verzeichnishandles WRITE_OWNER und WRITE_DAC Zugriff angeben. Wenn das Handle nicht über diese Zugriffsrechte verfügt, verweigert das Betriebssystem den Zugriff auf die ACL-Daten, und die Wiederherstellung der ACL-Daten erfolgt nicht.

[out] lpContext

Zeiger auf eine Variable, die einen Zeiger auf eine interne Datenstruktur empfängt, die von BackupWrite zum Verwalten von Kontextinformationen während eines Wiederherstellungsvorgangs verwendet wird.

Sie müssen die Variable, auf die von lpContext verwiesen wird, vor dem ersten Aufruf von BackupWrite für die angegebene Datei oder das angegebene Verzeichnis auf NULL festlegen. Die Funktion weist 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 BackupWrite verweist, nicht ändern.

Um den von der Datenstruktur verwendeten Arbeitsspeicher freizugeben, rufen Sie BackupWrite auf, wobei der bAbort-Parameter auf TRUE festgelegt ist, wenn der Wiederherstellungsvorgang abgeschlossen ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0, 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 Verwendung bei der Wiederherstellung von Dateien vorgesehen, die unter dem verschlüsselten Dateisystem verschlüsselt wurden. Verwenden Sie zu diesem Zweck WriteEncryptedFileRaw .

Die vom Sicherungsmedium gelesenen Daten müssen Teilströme sein, die durch WIN32_STREAM_ID Strukturen getrennt sind.

Mit dem BACKUP_LINK Streamtyp können Sie Dateien mit harten Links wiederherstellen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll