Fonction JetOpenFileInstance

S’applique à : Windows | Windows Server

Fonction JetOpenFileInstance

La fonction JetOpenFileInstance ouvre une base de données jointe, un fichier de 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 via le handle retourné à l’aide de JetReadFileInstance. Le handle retourné doit être fermé à l’aide de JetCloseFileInstance. Une sauvegarde externe du instance doit avoir été lancée précédemment à l’aide de JetBeginExternalBackupInstance.

Windows XP:JetOpenFileInstance est introduit dans Windows XP.

    JET_ERR JET_API JetOpenFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR szFileName,
      __out         JET_HANDLE* phfFile,
      __out         unsigned long* pulFileSizeLow,
      __out         unsigned long* pulFileSizeHigh
    );

Paramètres

instance

Instance à utiliser pour cet appel.

Pour Windows 2000, la variante d’API qui accepte ce paramètre n’est pas disponible, car une seule instance est prise en charge. L’utilisation de cette instance globale est implicite dans ce cas.

Pour Windows XP et les versions ultérieures, la variante d’API qui n’accepte pas ce paramètre ne peut être appelée que lorsque le moteur est en mode hérité (mode de compatibilité Windows 2000) où une seule instance est prise en charge. Sinon, l’opération échoue avec JET_errRunningInMultiInstanceMode.

szFileName

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

phfFile

Pointeur vers la mémoire tampon de sortie qui reçoit un handle pour le fichier à lire.

pulFileSizeLow

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

pulFileSizeHigh

Pointeur vers la 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 à JetStopBackupInstance. 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 toute activité sur le instance associée à la session a cessé à la suite d’un appel à JetStopServiceInstance.
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 chemin d’accès spécifié. Cette erreur ne sera retournée que par Windows 2000.
JET_errInvalidBackupSequence	L’opération de sauvegarde a échoué, car elle a été appelée hors séquence.
JET_errInvalidPath	L’opération a échoué, car le chemin d’accès spécifié est introuvable.
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 nécessite 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_errInvalidParameter	L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas pertinente lorsqu’elle était combinée avec la valeur d’un autre paramètre. Cela peut se produire pour JetOpenFileInstance dans les cas suivants : Le handle de 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_errMissingFileToBackup	Impossible d’ouvrir le fichier demandé pour 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 la mémoire n’a pas pu être allouée pour la terminer. JetOpenFileInstance 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 JetOpenFileInstance ait été fermé par JetCloseFileInstance. Un seul handle de fichier en attente est actuellement pris en charge.
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.
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’il existe déjà plusieurs instances.
JET_errTermInProgress	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.

En cas de réussite, un handle du fichier demandé est retourné. Si le handle est destiné à un fichier de base de données, ce fichier de base de données est préparé pour une sauvegarde de streaming 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 et le même nom de fichier que le fichier de base de données, mais avec 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 de correctif de base de données peut être créé temporairement sur le disque et tout fichier existant à l’emplacement du fichier de 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 ne sera 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 a été effectuée.

Avertissement Pour des raisons de sécurité, il est important de noter que JetOpenFileInstance ne vérifie pas que le chemin du fichier demandé est associé au jeu de fichiers 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 de divulgation 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.

À ce stade, un seul fichier peut être ouvert pour sauvegarde à tout moment.

JetOpenFileInstance 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 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 doit uniquement s’appuyer sur la taille de fichier retournée par JetOpenFileInstance ou sur le nombre réel d’octets de données retournés par JetReadFileInstance.

Spécifications

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

Voir aussi

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance