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。

[in, optional] plsnHigh

指向 CLFS_LSN 结构的指针，该结构指定活动日志客户端需要日志存档信息的活动日志范围的高端 LSN。

如果省略此参数，则范围的高端默认为要写入日志的下一个 LSN。

[out, optional] pcActualLength

指向变量的指针，该变量接收基本日志路径的名称的实际长度（以字符为单位）。

如果此值大于 cLen，则函数返回ERROR_BUFFER_OVERFLOW状态，其中包含存储在 pszBaseLogFileName 缓冲区中的截断路径以及未设置为有意义的值的所有其他 out 参数。

[out] poffBaseLogFileData

指向变量的指针，该变量接收元数据在基本日志中开始的偏移量。

基本日志 pszBaseLogFileName 中的连续范围表示日志元数据的完整内容，即从 poffBaseLogFileData 到 bbaseLogFileLength。

[out] pcbBaseLogFileLength

指向变量的指针，该变量指定基日志的确切长度（以字节为单位）。

[out] plsnBase

指向 CLFS_LSN 结构的指针，用于接收活动日志的 LSN) (基本日志序列号。

[out] plsnLast

指向 CLFS_LSN 结构的指针，用于接收活动日志中最高的有效 LSN。

[out] plsnCurrentArchiveTail

指向 CLFS_LSN 结构的指针，用于接收日志存档尾部的当前 LSN。

[out] ppvArchiveContext

指向变量的指针，该变量接收指向系统分配的存档上下文的指针。

存档上下文维护存档迭代器和日志句柄上下文的游标状态。 存档客户端负责通过调用 TerminateLogArchive 来释放上下文。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。 以下列表标识了可能的错误代码：

注解

必须调用 TerminateLogArchive 来释放存档上下文，否则可能会发生内存泄漏。

在调用 TerminateLogArchive 之前，无法回收正在存档的容器。

对于 CreateLogFile 返回的每个句柄，一次只能执行一个存档操作。

要求

另请参阅

CLFS_LSN

常见日志文件系统函数

GetNextLogArchiveExtent

ReadLogArchiveMetadata

TerminateLogArchive