次の方法で共有

JetOpenFileInstance 関数

  • [アーティクル]

適用対象: Windows |Windows Server

JetOpenFileInstance 関数

JetOpenFileInstance 関数は、ストリーミング あいまいバックアップを実行するために、アクティブ なインスタンスのアタッチされたデータベース、データベース パッチ ファイル、またはトランザクション ログ ファイルを開きます。 これらのファイルのデータは、 JetReadFileInstance を使用して、返されたハンドルを介して読み取ることができます。 返されるハンドルは、 JetCloseFileInstance を使用して閉じる必要があります。 インスタンスの外部バックアップは、 JetBeginExternalBackupInstance を使用して以前に開始されている必要があります。

Windows XP:JetOpenFileInstance は 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
    );

パラメーター

instance

この呼び出しに使用するインスタンス。

Windows 2000 の場合、このパラメーターを受け入れる API バリアントは使用できません。サポートされているインスタンスは 1 つだけであるためです。 この場合、この 1 つのグローバル インスタンスの使用が暗黙的に示されます。

Windows XP 以降のリリースでは、このパラメーターを受け入れない API バリアントは、1 つのインスタンスのみがサポートされているレガシ モード (Windows 2000 互換モード) の場合にのみ呼び出すことができます。 それ以外の場合、操作はJET_errRunningInMultiInstanceModeで失敗します。

szFileName

バックアップ用に読み取られたインスタンスによって管理される、アタッチされたデータベース、データベース パッチ ファイル、またはトランザクション ログ ファイルへの相対パスまたは絶対パス。

phfFile

読み取るファイルへのハンドルを受け取る出力バッファーへのポインター。

pulFileSizeLow

ファイルのサイズの下位 32 ビットを受け取る出力バッファーへのポインター。

pulFileSizeHigh

ファイルのサイズの最も重要な 32 ビットを受け取る出力バッファーへのポインター。

戻り値

この関数は、次のいずれかのリターン コードを使用して 、JET_ERR データ型を返します。 考えられる ESE エラーの詳細については、「 拡張可能ストレージ エンジン エラー 」および「 エラー処理パラメーター」を参照してください。

リターン コード

説明

JET_errSuccess

操作は正常に完了しました。

JET_errBackupAbortByServer

JetStopBackupInstance の呼び出しによって現在の外部バックアップが中止されたため、操作は失敗しました。 このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errClientRequestToStopJetService

JetStopServiceInstance の呼び出しの結果、セッションに関連付けられたインスタンス上のすべてのアクティビティが停止したため、操作を完了することはできません。

JET_errFileAccessDenied

共有違反または特権が不十分なため、要求されたファイルを開けなかったため、操作は失敗しました。

JET_errFileNotFound

指定したパスで見つからなかったため、要求されたファイルを開けなかったため、操作は失敗しました。 このエラーは Windows 2000 によってのみ返されます。

JET_errInvalidBackupSequence

バックアップ操作が順番に呼び出されたため、失敗しました。

JET_errInvalidPath

指定したパスが見つからなかったため、操作は失敗しました。

JET_errInstanceUnavailable

セッションに関連付けられているインスタンスで致命的なエラーが発生したため、操作を完了できません。このエラーでは、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要があります。 このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errInvalidParameter

指定されたパラメーターの 1 つに、予期しない値が含まれていたか、別のパラメーターの値と組み合わせると意味のない値が含まれていました。 これは、次の場合に JetOpenFileInstance で 発生する可能性があります。

  • 指定されたインスタンス ハンドルが無効です (Windows XP 以降のリリース)。

  • 指定した filename パラメーターは NULL または長さ 0 の文字列 (Windows XP 以降のリリース) です。

JET_errMissingFileToBackup

要求されたファイルが見つからなかったため、バックアップ用に開くことができませんでした。 このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errNoBackup

外部バックアップが進行中でないため、操作は失敗しました。

JET_errNotInitialized

セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。

JET_errOutOfMemory

完了するのに十分なメモリを割り当てられなかったため、操作が失敗しました。 JetOpenFileInstance を使用して開いた前のファイルが JetCloseFileInstance によって閉じられる前に別のファイルを開こうとした場合、 JetOpenFileInstance はJET_errOutOfMemoryを返します。 現在サポートされている未処理のファイル ハンドルは 1 つだけです。

JET_errRestoreInProgress

セッションに関連付けられているインスタンスで復元操作が進行中であるため、操作を完了できません。

JET_errRunningInMultiInstanceMode

実際に複数のインスタンスが既に存在する場合、1 つのインスタンスのみがサポートされているレガシ モード (Windows 2000 互換モード) でエンジンを使用しようとしたため、操作は失敗しました。

JET_errTermInProgress

セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。

成功すると、要求されたファイルへのハンドルが返されます。 ハンドルがデータベース ファイルの場合、そのデータベース ファイルはストリーミング バックアップ用に準備され、データベース ファイルと同じ場所にデータベース パッチ ファイルが作成される可能性があります。 データベース パッチ ファイルのパスとファイル名は、データベース ファイルとまったく同じですが、 は です。PAT 拡張機能。 ファイルのサイズも返されます。

失敗した場合、出力バッファーの状態は未定義になります。 データベースパッチファイルはディスク上に一時的に作成され、パッチファイルの場所にある既存のファイルは削除される可能性があります。 エラーが発生すると、インスタンスのバックアップ プロセス全体が取り消されます。 Windows XP 以降のリリースでは、呼び出し時にインスタンスにアタッチされていないデータベースをバックアップしようとした場合、バックアップは取り消されません。

警告 セキュリティ上の理由から、 JetOpenFileInstance では、要求されたファイル パスがインスタンス用にバックアップされたファイルのセットに関連付けられていることを確認しないことに注意してください。 その結果、この関数を使用して、スレッドの現在のセキュリティ コンテキストで開くことができるすべてのファイルにアクセスできます。 アプリケーションでは、この関数に渡されるパスを既知の適切なファイル パスのセットに制限するか、情報攻撃の開示を可能にすることが不可欠です。

注釈

ハンドルとファイル サイズの出力バッファーが存在する必要があります。 存在しない場合、出力バッファー パラメーターが検証されないため、エンジンがクラッシュします。

現時点では、バックアップ用に一度に開くことができるファイルは 1 つだけです。

JetOpenFileInstance は、要求されたファイルを開く前にバックアップ特権をアサートしません。

この関数によって報告される読み取り対象ファイルのサイズが、ディスク上のファイルのサイズと一致しない可能性があります。 Windows XP 以降のリリースでは、復元操作中にデータベース エンジンによって使用されるデータベース ファイルに追加情報が追加される場合があります。 そのため、アプリケーションは JetOpenFileInstance によって返されるファイル サイズ、または JetReadFileInstance によって返されるデータの実際のバイト数にのみ依存する必要があります。

要件

要件 値

Client

Windows Vista または Windows XP が必要です。

[サーバー]

Windows Server 2008 または Windows Server 2003 が必要です。

Header

Esent.h で宣言されています。

Library

ESENT.lib を使用します。

[DLL]

ESENT.dllが必要です。

Unicode

JetOpenFileInstanceW (Unicode) および JetOpenFileInstanceA (ANSI) として実装されます。

参照

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance