JetOpenFileInstance 函式

發行項
06/13/2023

適用于： 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 變體。在此情況下，會隱含使用此一個全域實例。

針對 Windows XP 和更新版本，只有在引擎處於舊版模式 (Windows 2000 相容性模式時，才能呼叫不接受此參數的 API 變體，) 其中僅支援一個實例。否則，作業將會失敗，並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	提供的其中一個參數包含非預期的值，或包含與另一個參數值結合時沒有意義的值。當下列情況時， JetOpenFileInstance 可能會發生這種情況：指定的實例控制碼 (Windows XP 和更新版本) 無效。指定的 filename 參數為 Null 或零長度字串， (Windows XP 和更新版本) 。
JET_errMissingFileToBackup	無法開啟要求的檔案進行備份，因為它找不到。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errNoBackup	作業失敗，因為沒有任何外部備份正在進行中。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errOutOfMemory	作業失敗，因為無法配置足夠的記憶體來完成作業。 JetOpenFileInstance如果嘗試在先前使用 JetOpenFileInstance 開啟的檔案之前開啟另一個檔案，則JetCloseFileInstance會傳回JET_errOutOfMemory。目前僅支援一個未處理的檔案控制碼。
JET_errRestoreInProgress	因為與會話相關聯的實例上正在進行還原作業，所以無法完成作業。
JET_errRunningInMultiInstanceMode	作業失敗，因為嘗試在舊版模式中使用引擎， (Windows 2000 相容性模式) 實際上只有一個實例存在時才支援。
JET_errTermInProgress	因為與會話相關聯的實例正在關閉，所以無法完成作業。

成功時，會傳回要求的檔案控制碼。如果控制碼適用于資料庫檔案，該資料庫檔案將會針對串流備份做好準備，這可能會導致資料庫修補程式檔案在與資料庫檔案相同的位置建立。資料庫修補程式檔案的路徑和檔案名與資料庫檔案完全相同，但具有。PAT 延伸模組。也會傳回檔案的大小。

失敗時，輸出緩衝區的狀態將會未定義。資料庫修補程式檔案可能會在磁片上暫時建立，而且修補檔位置上的任何現有檔案都可能會遭到刪除。失敗會導致實例的整個備份程式取消。在 Windows XP 和更新版本上，如果嘗試備份未在呼叫時附加至實例的資料庫，將不會取消備份。

警告基於安全性考慮，請務必注意 JetOpenFileInstance 不會驗證要求的檔案路徑是否與實例備份的檔案集相關聯。因此，您可以使用此函式來存取執行緒目前安全性內容可以開啟的任何檔案。應用程式必須將傳遞至此函式的路徑限制為已知的一組良好檔案路徑，或可能會洩漏資訊攻擊。

備註

需要有控制碼和檔案大小輸出緩衝區。如果它們不存在，引擎將會當機，因為不會驗證輸出緩衝區參數。

目前，隨時只能開啟一個檔案進行備份。

JetOpenFileInstance 不會在開啟要求的檔案之前判斷提示備份許可權。

此函式所報告要讀取的檔案大小可能與磁片上的檔案大小不符。在 Windows XP 和更新版本上，額外的資訊可能會附加至資料庫檔案，在還原作業期間由資料庫引擎使用。因此，應用程式應該只依賴 JetOpenFileInstance 所傳回的檔案大小，或 JetReadFileInstance所傳回的實際位元組數。

規格需求

需求	值
用戶端	需要 Windows Vista 或 Windows XP。
Server	需要 Windows Server 2008 或 Windows Server 2003。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。
Unicode	實作為 JetOpenFileInstanceW (Unicode) 和 JetOpenFileInstanceA (ANSI) 。

另請參閱

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance

共用方式為

JetOpenFileInstance 函式