PrepareLogArchive 函式 (clfsw32.h)

準備實體記錄以進行封存。 函式會擷取目前使用中記錄檔的快照集、為使用中記錄範圍建置一組已排序的記錄封存描述元，並傳回記錄封存內容。

藉由將此記錄封存內容傳遞至 GetNextLogArchiveExtent，用戶端就可以逐一查看記錄封存範圍集來封存記錄。 您也可以指定要封存的記錄範圍。

語法

CLFSUSER_API BOOL PrepareLogArchive(
  [in]            HANDLE                    hLog,
  [in, out]       PWSTR                     pszBaseLogFileName,
  [in]            ULONG                     cLen,
  [in, optional]  const PCLFS_LSN           plsnLow,
  [in, optional]  const PCLFS_LSN           plsnHigh,
  [out, optional] PULONG                    pcActualLength,
  [out]           PULONGLONG                poffBaseLogFileData,
  [out]           PULONGLONG                pcbBaseLogFileLength,
  [out]           PCLFS_LSN                 plsnBase,
  [out]           PCLFS_LSN                 plsnLast,
  [out]           PCLFS_LSN                 plsnCurrentArchiveTail,
  [out]           PCLFS_LOG_ARCHIVE_CONTEXT ppvArchiveContext
);

參數

[in] hLog

成功呼叫 CreateLogFile 所取得之記錄的句柄。

此句柄可以是專用或多任務記錄的句柄。

[in, out] pszBaseLogFileName

使用者配置的緩衝區指標，可接收基底記錄檔的完整路徑。

如果緩衝區不夠大，它會在結束時包含截斷的檔案路徑，而且函式會失敗並 出現ERROR_BUFFER_OVERFLOW 狀態代碼。

檔案路徑的長度會在 pcActualLength所指向的變數中傳回。 用戶端可以使用夠大的名稱緩衝區，重新嘗試失敗的呼叫。

[in] cLen

pszBaseLogFileName 緩衝區的大小，以寬字元表示。

[in, optional] plsnLow

CLFS_LSN 結構的指標，指定記錄檔用戶端需要記錄檔封存資訊的低端 LSN (LSN) 。

如果省略此參數，則範圍的低端預設為記錄封存結尾的 LSN。

[in, optional] plsnHigh

CLFS_LSN 結構的指標，指定記錄用戶端需要記錄檔封存資訊之使用中記錄檔範圍高階的 LSN。

如果省略此參數，範圍的高端預設為要寫入記錄的下一個 LSN。

[out, optional] pcActualLength

變數的指標，以字元為單位，接收基底記錄路徑名稱的實際長度。

如果這個值大於 cLen，則函式會傳回ERROR_BUFFER_OVERFLOW狀態，其中包含儲存在 pszBaseLogFileName 緩衝區中的截斷路徑，以及未設定為有意義值的其他所有 out 參數。

[out] poffBaseLogFileData

變數的指標，可接收元數據開始在基底記錄檔中的位移。

基底記錄 pszBaseLogFileName 中的連續範圍代表記錄元數據的完整內容，也就是從 poffBaseLogFileData 到 azureBaseLogFileLength。

[out] pcbBaseLogFileLength

變數的指標，指定基底記錄檔的確切長度，以位元組為單位。

[out] plsnBase

CLFS_LSN 結構的指標 ，可接收使用中記錄檔的 LSN) 基底記錄 (序號。

[out] plsnLast

要接收使用中記錄檔中最高有效 LSN 之CLFS_LSN 結構的指標。

[out] plsnCurrentArchiveTail

CLFS_LSN 結構的指標 ，可接收記錄檔結尾的目前 LSN。

[out] ppvArchiveContext

變數的指標，接收系統配置之封存內容的指標。

封存內容會維護封存反覆運算器和記錄句柄內容的游標狀態。 封存客戶端負責呼叫 TerminateLogArchive 來釋放內容。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 下列清單會識別可能的錯誤碼：

備註

您必須呼叫 TerminateLogArchive 來釋放封存內容，或可能發生記憶體流失。

在您呼叫 TerminateLogArchive 之前，無法回收封存的容器。

每個 CreateLogFile 傳 回的句柄一次只能執行一個封存作業。

規格需求

另請參閱

CLFS_LSN

一般記錄檔系統函式

GetNextLogArchiveExtent

ReadLogArchiveMetadata

TerminateLogArchive