BackupWrite, fonction (winbase.h)

Article
08/27/2023

La fonction BackupWrite peut être utilisée pour restaurer un fichier ou un répertoire sauvegardé à l’aide de BackupRead. Utilisez la fonction ReadFile pour obtenir un flux de données à partir du support de sauvegarde, puis utilisez BackupWrite pour écrire les données dans le fichier ou le répertoire spécifié.

Syntaxe

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

Paramètres

[in] hFile

Gérez le fichier ou le répertoire à restaurer. Pour obtenir le handle, appelez la fonction CreateFile . Les fichiers SACL ne sont pas restaurés, sauf si le handle de fichier a été créé avec le droit d’accès ACCESS_SYSTEM_SECURITY . Pour garantir que les AE d’intégrité sont correctement restaurées, le handle de fichier doit également avoir été créé avec le droit d’accès WRITE_OWNER . Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

Le handle doit être synchrone (non indébordé). Cela signifie que l’indicateur FILE_FLAG_OVERLAPPED ne doit pas être défini lorsque CreateFile est appelé. Cette fonction ne valide pas que le handle qu’elle reçoit est synchrone, donc elle ne retourne pas de code d’erreur pour un handle synchrone, mais l’appel à l’aide d’un handle asynchrone (qui se chevauche) peut entraîner des erreurs subtiles qui sont très difficiles à déboguer.

La fonction BackupWrite peut échouer si CreateFile a été appelé avec l’indicateur FILE_FLAG_NO_BUFFERING. Dans ce cas, la fonction GetLastError retourne la valeur ERROR_INVALID_PARAMETER.

[in] lpBuffer

Pointeur vers une mémoire tampon à partir de laquelle la fonction écrit des données.

[in] nNumberOfBytesToWrite

Taille de la mémoire tampon, en octets. La taille de la mémoire tampon doit être supérieure à la taille d’une structure WIN32_STREAM_ID .

[out] lpNumberOfBytesWritten

Pointeur vers une variable qui reçoit le nombre d’octets écrits.

[in] bAbort

Indique si vous avez terminé d’utiliser BackupWrite sur le handle. Pendant la restauration du fichier, spécifiez ce paramètre comme FALSE. Une fois que vous avez terminé d’utiliser BackupWrite, vous devez appeler BackupWrite une fois de plus en spécifiant TRUE pour ce paramètre et en passant le lpContext approprié. lpContext doit être passé lorsque bAbort a la valeur TRUE ; tous les autres paramètres sont ignorés.

[in] bProcessSecurity

Spécifie si la fonction restaure les données de la liste de contrôle d’accès (ACL) pour le fichier ou le répertoire.

Si bProcessSecurity a la valeur TRUE, vous devez spécifier WRITE_OWNER et WRITE_DAC accès lors de l’ouverture du handle de fichier ou de répertoire. Si le handle ne dispose pas de ces droits d’accès, le système d’exploitation refuse l’accès aux données ACL et la restauration des données ACL ne se produit pas.

[out] lpContext

Pointeur vers une variable qui reçoit un pointeur vers une structure de données interne utilisée par BackupWrite pour gérer les informations de contexte pendant une opération de restauration.

Vous devez définir la variable pointée vers lpContext sur NULL avant le premier appel à BackupWrite pour le fichier ou le répertoire spécifié. La fonction alloue de la mémoire pour la structure de données, puis définit la variable pour qu’elle pointe vers cette structure. Vous ne devez pas modifier lpContext ou la variable vers laquelle il pointe entre les appels à BackupWrite.

Pour libérer la mémoire utilisée par la structure de données, appelez BackupWrite avec le paramètre bAbort défini sur TRUE une fois l’opération de restauration terminée.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est zéro, ce qui indique qu’une erreur d’E/S s’est produite. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Cette fonction n’est pas destinée à être utilisée dans la restauration de fichiers chiffrés sous le système de fichiers chiffré. Utilisez WriteEncryptedFileRaw à cet effet.

Les données lues à partir du support de sauvegarde doivent être des sous-flux séparés par WIN32_STREAM_ID structures.

Le type de flux BACKUP_LINK vous permet de restaurer des fichiers avec des liens durs.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

WriteEncryptedFileRaw