Fonction JetOpenFile

S’applique à : Windows | Windows Server

Fonction JetOpenFile

La fonction JetOpenFile ouvre une base de données jointe, un fichier correctif de base de données ou un fichier journal des transactions d’un instance actif dans le but d’effectuer une sauvegarde approximative en streaming. Les données de ces fichiers peuvent ensuite être lues dans le handle retourné à l’aide de JetReadFile. Le handle retourné doit être fermé à l’aide de JetCloseFile. Une sauvegarde externe du instance doit avoir été lancée précédemment à l’aide de JetBeginExternalBackup.

    JET_ERR JET_API JetOpenFile(
      __in          const tchar* szFileName,
      __out         JET_HANDLE* phfFile,
      __out         unsigned long* pulFileSizeLow,
      __out         unsigned long* pulFileSizeHigh
    );

Paramètres

szFileName

Chemin d’accès relatif ou absolu d’une base de données jointe, d’un fichier correctif de base de données ou d’un fichier journal des transactions géré par le instance qui sera lu pour sauvegarde.

phfFile

Mémoire tampon de sortie qui reçoit un handle pour le fichier à lire.

pulFileSizeLow

Mémoire tampon de sortie qui reçoit les 32 bits les moins significatifs de la taille du fichier.

pulFileSizeHigh

Mémoire tampon de sortie qui reçoit les 32 bits les plus significatifs de la taille du fichier.

Valeur renvoyée

Cette fonction retourne le type de données JET_ERR avec l’un des codes de retour suivants. Pour plus d’informations sur les erreurs ESE possibles, consultez Erreurs du moteur de stockage extensible et Paramètres de gestion des erreurs.

Code de retour	Description
JET_errSuccess	L’opération s’est terminée avec succès.
JET_errBackupAbortByServer	L’opération a échoué, car la sauvegarde externe actuelle a été abandonnée par un appel à JetStopBackup. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errClientRequestToStopJetService	Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associées à la session ont cessé à la suite d’un appel à JetStopService.
JET_errFileAccessDenied	L’opération a échoué, car elle n’a pas pu ouvrir le fichier demandé en raison d’une violation de partage ou de privilèges insuffisants.
JET_errFileNotFound	L’opération a échoué, car elle n’a pas pu ouvrir le fichier demandé, car il est introuvable au niveau du chemin spécifié. Cette erreur sera uniquement retournée par Windows 2000.
JET_errInstanceUnavailable	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session a rencontré une erreur irrécupérable qui exige que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errInvalidBackupSequence	L’opération de sauvegarde a échoué, car elle a été appelée hors séquence.
JET_errInvalidParameter	L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas logique lorsqu’elle était combinée à la valeur d’un autre paramètre. Cela peut se produire pour JetOpenFile lorsque : Le handle instance spécifié n’est pas valide (Windows XP et versions ultérieures). Le paramètre de nom de fichier spécifié est NULL ou une chaîne de longueur nulle (Windows XP et versions ultérieures).
JET_errInvalidPath	L’opération a échoué, car le chemin spécifié est introuvable.
JET_errMissingFileToBackup	Impossible d’ouvrir le fichier demandé pour la sauvegarde, car il est introuvable. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errNoBackup	L’opération a échoué, car aucune sauvegarde externe n’est en cours.
JET_errNotInitialized	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session n’a pas encore été initialisé.
JET_errOutOfMemory	L’opération a échoué, car il n’est pas possible d’allouer suffisamment de mémoire pour la terminer. JetOpenFile retourne JET_errOutOfMemory si une tentative d’ouverture d’un autre fichier est effectuée avant que le fichier précédent ouvert à l’aide de JetOpenFile ait été fermé par JetCloseFile. Un seul handle de fichier en attente est actuellement pris en charge.
JET_errRunningInMultiInstanceMode	L’opération a échoué car une tentative d’utilisation du moteur a été effectuée en mode hérité (mode de compatibilité Windows 2000) où une seule instance est prise en charge alors qu’en fait plusieurs instances existent déjà.
JET_errTermInProgress	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt. JET_errRestoreInProgress Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur le instance associé à la session.

En cas de réussite, un handle du fichier demandé est retourné. Si le handle concerne un fichier de base de données, ce fichier de base de données sera préparé pour la sauvegarde en streaming, ce qui peut entraîner la création d’un fichier correctif de base de données au même emplacement que le fichier de base de données. Le fichier correctif de base de données a exactement le même chemin d’accès et le même nom de fichier que le fichier de base de données, mais a un . Extension PAT. La taille du fichier sera également retournée.

En cas d’échec, l’état des mémoires tampons de sortie n’est pas défini. Un fichier correctif de base de données peut être créé temporairement sur le disque et tout fichier existant à l’emplacement du fichier correctif peut être supprimé. L’échec entraîne l’annulation de l’ensemble du processus de sauvegarde pour le instance. Sur Windows XP et les versions ultérieures, la sauvegarde n’est pas annulée si une tentative de sauvegarde d’une base de données qui n’était pas attachée au instance au moment de l’appel n’est pas effectuée.

Avertissement Pour des raisons de sécurité, il est important de noter que JetOpenFile ne vérifie pas que le chemin du fichier demandé est associé à l’ensemble de fichiers qui doivent être sauvegardés pour le instance. Par conséquent, il est possible d’utiliser cette fonction pour accéder à n’importe quel fichier qui peut être ouvert par le contexte de sécurité actuel du thread. Il est impératif que l’application limite les chemins passés à cette fonction à un ensemble connu de chemins d’accès corrects ou qu’une attaque d’informations puisse être rendue possible.

Notes

Les mémoires tampons de sortie de handle et de taille de fichier doivent être présentes. S’ils ne sont pas présents, le moteur se bloque, car les paramètres de mémoire tampon de sortie ne sont pas validés.

Pour le moment, un seul fichier peut être ouvert pour la sauvegarde à tout moment.

JetOpenFile n’affirme pas le privilège de sauvegarde avant d’ouvrir le fichier demandé.

La taille du fichier à lire comme indiqué par cette fonction peut ne pas correspondre à la taille du fichier sur le disque. Sur Windows XP et les versions ultérieures, des informations supplémentaires peuvent être ajoutées à un fichier de base de données utilisé par le moteur de base de données lors d’une opération de restauration. Par conséquent, l’application ne doit s’appuyer que sur la taille de fichier retournée par JetOpenFile ou sur le nombre réel d’octets de données retournés par JetReadFile.

Spécifications

Condition requise	Valeur
Client	Nécessite Windows Vista, Windows XP ou Windows 2000 Professionnel.
Serveur	Nécessite Windows Server 2008, Windows Server 2003 ou Windows 2000 Server.
En-tête	Déclaré dans Esent.h.
Bibliothèque	Utilisez ESENT.lib.
DLL	Nécessite ESENT.dll.
Unicode	Implémenté en tant que JetOpenFileW (Unicode) et JetOpenFileA (ANSI).

Voir aussi

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackup
JetCloseFile
JetGetAttachInfo
JetGetLogInfo
JetReadFile
JetStopBackup
JetStopService
JetTruncateLog