clfsReserveAndAppendLog 函数 (wdm.h)

ClfsReserveAndAppendLog 例程在封送区域中保留空间,或将记录追加到封送区域,或者以原子方式同时执行这两项操作。

语法

CLFSUSER_API NTSTATUS ClfsReserveAndAppendLog(
  [in]            PVOID             pvMarshalContext,
  [in, optional]  PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]            ULONG             cWriteEntries,
  [in, optional]  PCLFS_LSN         plsnUndoNext,
  [in, optional]  PCLFS_LSN         plsnPrevious,
  [in]            ULONG             cReserveRecords,
  [in, out]       PLONGLONG         rgcbReservation,
  [in]            ULONG             fFlags,
  [out, optional] PCLFS_LSN         plsn
);

参数

[in] pvMarshalContext

指向表示与 CLFS 流关联的封送区域的不透明上下文的指针。 调用方以前通过调用 ClfsCreateMarshallingArea 获取了此指针。

[in, optional] rgWriteEntries

指向 CLFS_WRITE_ENTRY 结构的数组的指针,其中每个结构都包含一个指向数据缓冲区的指针,该缓冲区将成为追加到日志的记录的一部分。 如果 cWriteEntries 为零,此参数可以为 NULL

[in] cWriteEntries

rgWriteEntries 指向的数组中的元素数。 如果 rgWriteEntries 为 NULL,则此参数必须为

[in, optional] plsnUndoNext

指向 CLFS_LSN 结构的指针,该结构提供要追加的记录的撤消下一个 LSN。

[in, optional] plsnPrevious

指向CLFS_LSN 结构的指针,该结构提供要追加的记录的上一个 LSN。

[in] cReserveRecords

rgcbReservation 指向的数组中的元素数。 如果 rgcbReservationNULL 或设置了 fFlags 的CLFS_FLAG_USE_RESERVATION标志,则此参数必须为零。

[in, out] rgcbReservation

指向 LONGLONG 类型变量数组的指针。 调用方将数组的每个元素设置为必须为其保留空间的记录的大小(以字节为单位)。 返回时,每个数组元素接收为记录保留的空间的实际大小。 这包括标头和对齐所需的空间。 如果预留值为负值,则会释放与所提供的负值的绝对值最接近的保留记录。 如果 cReserveRecords 为零,此参数可以为 NULL;如果设置了 fFlags 的CLFS_FLAG_USE_RESERVATION标志,此参数必须为 NULL

[in] fFlags

此参数可以是零,也可以是以下标志的任意组合。

标志 含义
CLFS_FLAG_FORCE_APPEND 将当前记录追加到日志 I/O 块后,该块将按 LSN 顺序排队到稳定存储。 此标志不保证将记录强制到稳定的存储 (看到CLFS_FLAG_FORCE_FLUSH) 。
CLFS_FLAG_FORCE_FLUSH 将当前记录追加到日志 I/O 块后,该块将被强制存储到稳定的存储中。
CLFS_FLAG_USE_RESERVATION 当前记录放置在封送处理区域内日志 I/O 块中的保留空间中。 封送处理区域中的保留记录数减少 1。 如果设置了此标志, cReserveRecords 必须为零, rgcbReservation 必须为 NULL

[out, optional] plsn

指向接收追加记录的 LSN 的 CLFS_LSN 结构的指针。 如果 cWriteEntries 为零,此参数可以为 NULL

返回值

ClfsReserveAndAppendLog 如果成功,则返回STATUS_SUCCESS;否则,它将返回 Ntstatus.h 中定义的错误代码之一。

注解

ClfsReserveAndAppendLog 例程根据是否存在可选参数和CLFS_USE_RESERVATION标志的状态更改其基本行为。 下表总结了常见方案。

参数和标志值 执行的操作
cWriteEntries = 0。

rgWriteEntries = NULL

plsn = NULL

为一组记录保留空间,但不将记录追加到封送处理区域。 rgcbReservation 参数提供需要保留空间的每个记录的数据部分的大小。
cWriteEntries > 0。

rgWriteEntries 不为 NULL

plsn 不为 NULL

cReserveRecords = 0。

rgcbReservationNULL

设置CLFS_USE_RESERVATION。

使用已保留的空间将记录追加到封送区域。 将保留的记录空间数减少 1。
cWriteEntries > 0。

rgWriteEntries 不为 NULL

plsn 不为 NULL

cReserveRecords = 0。

rgcbReservationNULL

清除CLFS_USE_RESERVATION。

通过保留新空间将记录追加到封送区域。 保留的记录空间数保持不变。
cWriteEntries > 0。

rgWriteEntries 不为 NULL

plsn 不为 NULL

cReserveRecords> 0.

rgcbReservation 不为 NULL

清除CLFS_USE_RESERVATION标志。

通过保留新空间将记录追加到封送区域。 此外,还会为此时未追加的一组记录保留空间。 rgcbReservation 参数提供需要保留空间的每个记录的大小。 将保留的记录空间数增加 cReserveRecords 的值。
 

调用 ClfsReserveAndAppendLog 等效于调用 ClfsReserveAndAppendLogAligned ,并将 cbEntryAlignment 参数设置为 1。

有关 CLFS 概念和术语的说明,请参阅 通用日志文件系统

要求

要求
最低受支持的客户端 在 Windows Server 2003 R2、Windows Vista 和更高版本的 Windows 中可用。
目标平台 桌面
标头 wdm.h (包括 Wdm.h)
Library Clfs.lib
DLL Clfs.sys
IRQL <= APC_LEVEL

另请参阅

CLFS_LSN

CLFS_WRITE_ENTRY

ClfsCreateMarshallingArea

ClfsReserveAndAppendLogAligned