ClfsCreateLogFile 函数 (wdm.h)

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 是否大于零。 否则, 将忽略 pvContextcbContext
CLFS_FLAG_REENTRANT_FILE_SYSTEM 创建组件是为 CLFS 提供基础存储的文件系统。 CLFS 使用文件系统分配容器,文件系统使用 CLFS 流。 在这种情况下,文件系统可以调用 CLFS,CLFS 可以调用同一线程或不同线程上的文件系统。 如果 pvContext 不为 NULL,则 CLFS 会验证 cbContext 是否大于零。 否则, 将忽略 pvContextcbContext
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