JetOpenFileInstance-Funktion

Gilt für: Windows | Windows Server

JetOpenFileInstance-Funktion

Die JetOpenFileInstance-Funktion öffnet eine angefügte Datenbank, eine Datenbankpatchdatei oder eine Transaktionsprotokolldatei einer aktiven Instanz, um eine Streaming-Fuzzysicherung durchführen zu können. Die Daten aus diesen Dateien können anschließend mit jetReadFileInstanceüber das zurückgegebene Handle gelesen werden. Das zurückgegebene Handle muss mit JetCloseFileInstance geschlossen werden. Eine externe Sicherung der Instanz muss zuvor mit JetBeginExternalBackupInstance initiiert worden sein.

**Windows XP:**JetOpenFileInstance wird in Windows XP eingeführt.

    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
    );

Parameter

Instanz

Die -Instanz, die für diesen Aufruf verwendet werden soll.

Für Windows 2000 ist die API-Variante, die diesen Parameter akzeptiert, nicht verfügbar, da nur eine Instanz unterstützt wird. Die Verwendung dieser einen globalen Instanz wird in diesem Fall impliziert.

Für Windows XP und spätere Versionen kann die API-Variante, die diesen Parameter nicht akzeptiert, nur aufgerufen werden, wenn sich die Engine im Legacymodus (Windows 2000-Kompatibilitätsmodus) befindet, in dem nur eine Instanz unterstützt wird. Andernfalls kann der Vorgang nicht durchgeführt JET_errRunningInMultiInstanceMode.

szFileName

Der relative oder absolute Pfad zu einer angefügten Datenbank, Datenbankpatchdatei oder Transaktionsprotokolldatei, die von der Instanz verwaltet wird, die für die Sicherung gelesen wird.

phfFile

Zeiger auf den Ausgabepuffer, der ein Handle für die zu lesende Datei empfängt.

pulFileSizeLow

Zeiger auf den Ausgabepuffer, der die am wenigsten signifikanten 32 Bits der Dateigröße empfängt.

pulFileSizeHigh

Zeiger auf den Ausgabepuffer, der die signifikantesten 32 Bits der Dateigröße empfängt.

Rückgabewert

Diese Funktion gibt den JET_ERR-Datentyp mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu den möglichen ESE-Fehlern finden Sie unter Extensible Storage Engine Errors and Error Handling Parameters.

Rückgabecode

Beschreibung

JET_errSuccess

Der Vorgang wurde erfolgreich abgeschlossen.

JET_errBackupAbortByServer

Fehler beim Vorgang, weil die aktuelle externe Sicherung durch einen Aufruf von JetStopBackupInstance abgebrochen wurde. Dieser Fehler wird nur von xp Windows und späteren Versionen zurückgegeben.

JET_errClientRequestToStopJetService

Es ist nicht möglich, den Vorgang abschließen, da alle Aktivitäten auf der -Instanz, die der Sitzung zugeordnet ist, aufgrund eines Aufrufs von JetStopServiceInstance beendet wurden.

JET_errFileAccessDenied

Der Vorgang ist fehlgeschlagen, da die angeforderte Datei aufgrund einer Freigabeverletzung oder unzureichender Berechtigungen nicht geöffnet werden konnte.

JET_errFileNotFound

Fehler beim Vorgang, da die angeforderte Datei nicht geöffnet werden konnte, weil sie am angegebenen Pfad nicht gefunden wurde. Dieser Fehler wird nur von Windows 2000 zurückgegeben.

JET_errInvalidBackupSequence

Fehler beim Sicherungsvorgang, weil er nicht sequenziert aufgerufen wurde.

JET_errInvalidPath

Fehler beim Vorgang, weil der angegebene Pfad nicht gefunden werden konnte.

JET_errInstanceUnavailable

Der Vorgang kann nicht abgeschlossen werden, da für die der Sitzung zugeordnete Instanz ein schwerwiegender Fehler aufgetreten ist, der erfordert, dass der Zugriff auf alle Daten widerrufen wird, um die Integrität dieser Daten zu schützen. Dieser Fehler wird nur von xp Windows und späteren Versionen zurückgegeben.

JET_errInvalidParameter

Einer der bereitgestellten Parameter enthielt einen unerwarteten Wert oder einen Wert, der in Kombination mit dem Wert eines anderen Parameters nicht sinnvoll war. Dies kann für JetOpenFileInstance passieren, wenn:

  • Das angegebene Instanzhand handle ist ungültig (Windows XP und spätere Versionen).

  • Der angegebene Dateinamenparameter ist NULL oder eine Zeichenfolge der Länge 0 (Windows XP und spätere Releases).

JET_errMissingFileToBackup

Die angeforderte Datei konnte nicht für die Sicherung geöffnet werden, da sie nicht gefunden wurde. Dieser Fehler wird nur von xp Windows und späteren Versionen zurückgegeben.

JET_errNoBackup

Der Vorgang ist fehlgeschlagen, da keine externe Sicherung durchgeführt wird.

JET_errNotInitialized

Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete Instanz noch nicht initialisiert wurde.

JET_errOutOfMemory

Fehler beim Vorgang, da nicht genügend Arbeitsspeicher zugeordnet werden konnte, um ihn abschließen zu können. JetOpenFileInstance gibt JET_errOutOfMemory zurück, wenn versucht wird, eine andere Datei zu öffnen, bevor die vorherige Datei, die mit JetOpenFileInstance geöffnet wurde, von JetCloseFileInstance geschlossen wurde. Derzeit wird nur ein ausstehendes Dateihand handle unterstützt.

JET_errRestoreInProgress

Der Vorgang kann nicht abgeschlossen werden, da ein Wiederherstellungsvorgang für die -Instanz durchgeführt wird, die der Sitzung zugeordnet ist.

JET_errRunningInMultiInstanceMode

Der Vorgang ist fehlgeschlagen, weil versucht wurde, die Engine im Legacymodus (Windows 2000-Kompatibilitätsmodus) zu verwenden, wobei nur eine Instanz unterstützt wird, wenn tatsächlich bereits mehrere Instanzen vorhanden sind.

JET_errTermInProgress

Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete Instanz heruntergefahren wird.

Bei Erfolg wird ein Handle für die angeforderte Datei zurückgegeben. Wenn das Handle für eine Datenbankdatei gilt, wird diese Datenbankdatei für eine Streamingsicherung vorbereitet, was zur Erstellung einer Datenbankpatchdatei am gleichen Speicherort wie die Datenbankdatei führen kann. Die Datenbankpatchdatei hat genau denselben Pfad und Dateinamen wie die Datenbankdatei, jedoch mit einem . PAT-Erweiterung. Die Größe der Datei wird ebenfalls zurückgegeben.

Bei einem Fehler ist der Status der Ausgabepuffer nicht definiert. Eine Datenbankpatchdatei kann vorübergehend auf dem Datenträger erstellt werden, und alle vorhandenen Dateien am Speicherort der Patchdatei können gelöscht werden. Der Fehler führt zum Abbruch des gesamten Sicherungsprozesses für die Instanz. Bei Windows XP und späteren Versionen wird die Sicherung nicht abgebrochen, wenn versucht wurde, eine Datenbank zu sichern, die zum Zeitpunkt des Aufrufs nicht an die Instanz angefügt war.

Warnung Aus Sicherheitsgründen ist es wichtig zu beachten, dass JetOpenFileInstance nicht überprüft, ob der angeforderte Dateipfad dem Satz von Dateien zugeordnet ist, die für die Instanz sichern werden. Daher ist es möglich, diese Funktion für den Zugriff auf jede Datei zu verwenden, die vom aktuellen Sicherheitskontext des Threads geöffnet werden kann. Es ist zwingend erforderlich, dass die Anwendung die pfade, die an diese Funktion übergeben werden, auf einen bekannten Satz guter Dateipfade beschränkt, oder es kann ein Angriff auf die Offenlegung von Informationen möglich gemacht werden.

Hinweise

Die Ausgabepuffer für Handle und Dateigröße müssen vorhanden sein. Wenn sie nicht vorhanden sind, stürzt die Engine ab, da die Ausgabepufferparameter nicht überprüft werden.

Derzeit kann nur eine Datei gleichzeitig für die Sicherung geöffnet werden.

JetOpenFileInstance übernimmt die Sicherungsberechtigung nicht, bevor die angeforderte Datei geöffnet wird.

Die Größe der Datei, die gelesen werden soll, wie von dieser Funktion gemeldet, ist möglicherweise nicht mit der Größe der Datei auf dem Datenträger übereinstimmen. Bei Windows XP und späteren Versionen können zusätzliche Informationen an eine Datenbankdatei angefügt werden, die von der Datenbank-Engine während eines Wiederherstellungsvorgang verwendet wird. Daher sollte sich die Anwendung nur auf die dateigröße verlassen, die von JetOpenFileInstance zurückgegeben wird, oder auf der tatsächlichen Anzahl von Bytes von Daten, die von JetReadFileInstance zurückgegeben werden.

Anforderungen

Anforderung Wert

Client

Erfordert Windows Vista oder Windows XP.

Server

Erfordert Windows Server 2008 oder Windows Server 2003.

Header

Wird in Esent.h deklariert.

Bibliothek

Verwenden Sie ESENT.lib.

DLL

Erfordert ESENT.dll.

Unicode

Implementiert als JetOpenFileInstanceW (Unicode) und JetOpenFileInstanceA (ANSI).

Weitere Informationen

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance