BackupRead, fonction (winbase.h)

La fonction BackupRead peut être utilisée pour sauvegarder un fichier ou un répertoire, y compris les informations de sécurité. La fonction lit les données associées à un fichier ou répertoire spécifié dans une mémoire tampon, qui peut ensuite être écrite sur le support de sauvegarde à l’aide de la fonction WriteFile .

Syntaxe

BOOL BackupRead(
  [in]  HANDLE  hFile,
  [out] LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToRead,
  [out] LPDWORD lpNumberOfBytesRead,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Paramètres

[in] hFile

Gérez le fichier ou le répertoire à sauvegarder. Pour obtenir le handle, appelez la fonction CreateFile . Les FICHIERS SACL ne sont pas lus, sauf si le handle de fichier a été créé avec le droit d’accès ACCESS_SYSTEM_SECURITY . Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

Le handle doit être synchrone (sans couverture). 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. Elle ne retourne donc pas de code d’erreur pour un handle synchrone, mais l’appeler avec un handle asynchrone (qui se chevauche) peut entraîner des erreurs subtiles qui sont très difficiles à déboguer.

La fonction BackupRead 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.

[out] lpBuffer

Pointeur vers une mémoire tampon qui reçoit les données.

[in] nNumberOfBytesToRead

Longueur 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] lpNumberOfBytesRead

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

Si la fonction retourne une valeur différente de zéro et que la variable pointée par lpNumberOfBytesRead est égale à zéro, toutes les données associées au handle de fichier ont été lues.

[in] bAbort

Indique si vous avez terminé d’utiliser BackupRead sur le handle. Pendant que vous sauvegardez le fichier, spécifiez ce paramètre sur FALSE. Une fois que vous avez terminé d’utiliser BackupRead, vous devez appeler BackupRead 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

Indique 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, les données ACL sont sauvegardées.

[out] lpContext

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

Vous devez définir la variable pointée vers lpContext sur NULL avant le premier appel à BackupRead 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 à BackupRead.

Pour libérer la mémoire utilisée par la structure de données, appelez BackupRead avec le paramètre bAbort défini sur TRUE lorsque l’opération de sauvegarde est 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 sauvegarde de fichiers chiffrés sous le système de fichiers chiffré. Utilisez ReadEncryptedFileRaw à cet effet.

Si une erreur se produit pendant que BackupRead lit des données, le processus appelant peut ignorer les données incorrectes en appelant la fonction BackupSeek .

Le fichier ou le répertoire doit être restauré à l’aide de la fonction BackupWrite .

Configuration requise

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

BackupSeek

BackupWrite

Création d’une application de sauvegarde

ReadEncryptedFileRaw

WIN32_STREAM_ID