ClfsCreateLogFile 函数 (wdm.h)

项目
02/29/2024

ClfsCreateLogFile 例程创建或打开 CLFS 流。如有必要， ClfsCreateLogFile 还会创建保存流记录的基础物理日志。

语法

CLFSUSER_API NTSTATUS ClfsCreateLogFile(
  [out]          PPLOG_FILE_OBJECT    pplfoLog,
  [in]           PUNICODE_STRING      puszLogFileName,
  [in]           ACCESS_MASK          fDesiredAccess,
  [in]           ULONG                dwShareMode,
  [in, optional] PSECURITY_DESCRIPTOR psdLogFile,
  [in]           ULONG                fCreateDisposition,
  [in]           ULONG                fCreateOptions,
  [in]           ULONG                fFlagsAndAttributes,
  [in]           ULONG                fLogOptionFlag,
  [in, optional] PVOID                pvContext,
  [in]           ULONG                cbContext
);

参数

[out] pplfoLog

指向变量的指针，该变量接收指向表示流打开实例的LOG_FILE_OBJECT 结构的指针。

[in] puszLogFileName

指向 UNICODE_STRING 结构的指针，该结构提供流或基础物理日志的名称。

如果流已存在并且是专用日志的唯一流，则名称的格式为 log：physical 日志名称，其中 物理日志名称 是基础文件系统上包含流记录的现有物理日志的路径名称。

如果流尚不存在，并且要成为) 尚不存在的专用日志 (的唯一流，则名称的格式为 log：physical 日志名称，其中 物理日志名称 是基础文件系统上将创建的物理日志的路径名称，用于保存流记录。

如果流 (或要成为多路复用日志流之一) ，则名称的格式为 log：physical log name：：stream name，其中 物理日志名称 是基础文件系统上保存流记录的物理日志的路径名称， 流名称 是共享 (或将共享) 该物理日志的流的名称。

如果要创建目前没有流的多路复用日志，请使用要创建的物理日志的 log：physical log name：，其中 物理日志名称 是基础文件系统上要创建的物理日志的路径名称。

以下列表提供了一些有效名称的示例。

“Log：c：\myLog”创建或打开专用日志及其一个流。
“Log：c：\myCommonLog：：”创建尚没有任何流的多路复用日志。
“Log：c：\myCommonLog：：Stream1” (多路复用日志的 Stream1) 创建或打开其中一个流。

[in] fDesiredAccess

一个 ACCESS_MASK ，它通过使用 pplfoLog) 流返回的指针提供客户端将 (的访问类型。如果此参数为零，则客户端可以查询流中的属性，但无法从流中读取或写入流。此参数可以是零，也可以是以下标志的任意组合：

标志	含义
GENERIC_READ	客户端对流具有读取访问权限。
GENERIC_WRITE	客户端对流具有写入访问权限。
DELETE	客户端可以将流标记为要删除。

[in] dwShareMode

流的共享模式，可以是零 (不共享) 或以下标志的任意组合：

标志	含义
FILE_SHARE_DELETE	使用删除访问权限打开流的后续请求将成功。
FILE_SHARE_READ	使用读取访问权限打开流的后续请求将成功。
FILE_SHARE_WRITE	使用写入访问权限打开流的后续请求将成功。

[in, optional] psdLogFile

指向 SECURITY_DESCRIPTOR 结构的指针，该结构为流提供安全属性。此参数可以为 NULL。

[in] fCreateDisposition

要执行的操作取决于流是否已存在。此参数必须设置为以下值之一：

值	含义
CREATE_NEW	如果流尚未退出，请创建新流。如果流已存在，则失败。
OPEN_EXISTING	打开现有流。如果流尚不存在，则失败。
OPEN_ALWAYS	打开现有流。如果流尚不存在，请创建该流。

[in] fCreateOptions

一组标志，指定要在创建或打开流时应用的选项。此参数可以是零，也可以是以下标志的兼容组合：

标志	含义
FILE_NO_INTERMEDIATE_BUFFERING	流的记录不能缓存在驱动程序的内部缓冲区中。
FILE_SYNCHRONOUS_IO_ALERT	流上的所有操作都是同步执行的。代表调用方的任何等待都可能提前终止警报。如果设置了此标志，则必须清除FILE_SYNCHRONOUS_IO_NONALERT标志。
FILE_SYNCHRONOUS_IO_NONALERT	流上的所有操作都是同步执行的。同步 I/O 排队和完成的系统中的等待不受警报约束。如果设置了此标志，则必须清除FILE_SYNCHRONOUS_IO_ALERT标志。

[in] fFlagsAndAttributes

一个值，该值指定是打开流进行正常访问还是只读访问。此参数必须设置为两者之一

FILE_ATTRIBUTE_NORMAL或FILE_ATTRIBUTE_READONLY。

[in] fLogOptionFlag

有关 CLFS 与创建或打开流的组件之间的关系的提示。此参数必须设置为以下值之一：

值	含义
CLFS_FLAG_NO_FLAGS	CLFS 和创建组件具有标准的正常关系。内核模式组件使用此值，除非它们属于此表中列出的其他三个类别之一。如果 pvContext 不为 NULL，则 CLFS 会验证 cbContext 是否大于零。否则，将忽略 pvContext 和 cbContext 。
CLFS_FLAG_REENTRANT_FILE_SYSTEM	创建组件是为 CLFS 提供基础存储的文件系统。 CLFS 使用文件系统分配容器，文件系统使用 CLFS 流。在这种情况下，文件系统可以调用 CLFS，CLFS 可以调用同一线程或不同线程上的文件系统。如果 pvContext 不为 NULL，则 CLFS 会验证 cbContext 是否大于零。否则，将忽略 pvContext 和 cbContext 。
CLFS_FLAG_NON_REENTRANT_FILTER	创建组件是一个文件系统筛选器驱动程序，用于将其所有 CLFS I/O 发送到筛选器堆栈上自身下方的指定级别。此选项允许筛选器驱动程序创建 CLFS 日志，而无需看到自己的日志记录 I/O。调用方传递 pvContext 参数中的非 NULL 目标设备对象，并将 cbContext 设置为适当的大小。 CLFS 使用 IoCreateFileSpecifyDeviceObjectHint 例程在设备对象指定的 I/O 筛选器堆栈中的目标级别创建容器。
CLFS_FLAG_REENTRANT_FILTER	创建组件是一个文件系统筛选器驱动程序，用于将其所有 CLFS I/O 发送到筛选器堆栈顶部。筛选器与 CLFS 有递归关系，因为它在 CLFS 对其容器执行任何文件系统操作时筛选自己的日志记录 I/O。当日志 I/O 进入筛选器堆栈时， pvContext 参数为筛选器提供了一种将可识别上下文与其 CLFS 容器相关联的方法。 cbContext 参数指定不透明上下文的大小（以字节为单位）。
CLFS_FLAG_MINIFILTER_LEVEL	创建组件是一个文件系统微筛选器驱动程序，用于将其所有 CLFS I/O 发送到筛选器堆栈上自身下方的指定级别。此选项允许微筛选器创建 CLFS 日志，而无需看到自己的日志记录 I/O。调用方传递 pvContext 参数中的非 NULL 微筛选器上下文对象，并将 cbContext 设置为适当的大小。 CLFS 使用 IoCreateFileSpecifyDeviceObjectHint 例程在筛选器管理器的微筛选器堆栈中的微筛选器上下文) 指定的高度 (创建容器。

[in, optional] pvContext

指向上下文的指针。解释上下文的方式取决于传递给 fLogOptionsFlag 的值。

[in] cbContext

pvContext 指向的上下文的大小（以字节为单位）。如果 pvContext 不为 NULL，则此参数必须大于零。

返回值

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

注解

创建 CLFS 流时，它由基础物理 CLFS 日志提供支持。基础日志可以是专用 (仅支持一个流) ，也可以是多路复用 () 支持多个流。专用日志无法转换为多路复用日志，多路复用日志不能转换为专用日志。

物理 CLFS 日志名称不包括 .blf 扩展名。

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

要求

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

另请参阅

ClfsCloseAndResetLogFile

ClfsCloseLogFileObject

ClfsDeleteLogByPointer

ClfsDeleteLogFile

通过

ClfsCreateLogFile 函数 (wdm.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源