通过

FltCreateNamedPipeFile 函数 （fltkernel.h）

  • 项目

微型筛选器驱动程序调用 FltCreateNamedPipeFile 创建新的管道或打开现有管道。

语法

NTSTATUS FLTAPI FltCreateNamedPipeFile(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ULONG                     DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in]            ULONG                     NamedPipeType,
  [in]            ULONG                     ReadMode,
  [in]            ULONG                     CompletionMode,
  [in]            ULONG                     MaximumInstances,
                  ULONG                     InboundQuota,
                  ULONG                     OutboundQuota,
  [in, optional]  PLARGE_INTEGER            DefaultTimeout,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

参数

[in] Filter

调用方不透明的筛选器指针。

[in, optional] Instance

要将创建请求发送到的微型筛选器驱动程序实例的不透明实例指针。 该实例必须附加到命名管道文件系统的卷。 此参数是可选的，可以 NULL。 如果此参数 NULL，则请求将发送到卷文件系统驱动程序堆栈顶部的设备对象。 如果它是非NULL，则请求仅发送到附加到指定实例下方的微型筛选器驱动程序实例。

[out] FileHandle

指向调用方分配的变量的指针，如果调用 FltCreateNamedPipeFile 成功，则接收文件句柄。

[out, optional] FileObject

指向调用方分配的变量的指针，如果调用 FltCreateNamedPipeFile 成功，则接收文件对象指针。 此参数是可选的，可以 NULL。

[in] DesiredAccess

指定调用方对文件或目录所需的访问类型的标志的位掩码。 一组系统定义的 DesiredAccess 标志决定了文件对象的以下特定访问权限。

DesiredAccess 标志 意义
FILE_READ_DATA 可以从命名管道读取数据。
FILE_READ_ATTRIBUTES 可以读取 FileAttributes 标志。 有关详细信息，请参阅 FileAttributesFltCreateFileEx2参数中的有效标志值的表。
READ_CONTROL 可以读取访问控制列表（ACL）以及与命名管道关联的所有权信息。
FILE_WRITE_DATA 可以将数据写入命名管道。
FILE_WRITE_ATTRIBUTES FileAttributes 标志可以写入。
FILE_APPEND_DATA 可将数据追加到文件。
WRITE_DAC 可以编写与命名管道关联的自由访问控制列表（DACL）。
WRITE_OWNER 可以编写与命名管道关联的所有权信息。
ACCESS_SYSTEM_SECURITY 调用方将对命名管道的 SACL 具有写入访问权限
同步 调用方可以通过等待返回 FileHandle 设置为 Signaled 状态来同步 I/O作的完成。 如果设置了 CreateOptions FILE_SYNCHRONOUS_IO_ALERT 或FILE_SYNCHRONOUS_IO_NONALERT标志，则必须设置此标志。
 

或者，对于不表示目录的任何文件对象，可以指定以下一个或多个泛型 ACCESS_MASK 标志。 （STANDARD_RIGHTS_XXX 标志是用于在系统对象上强制实施安全性的预定义系统值。还可以将这些泛型标志与上表中的其他标志组合在一起。

DesiredAccess 到文件值 映射到 DesiredAccess 标志
GENERIC_READ STANDARD_RIGHTS_READ、FILE_READ_DATA 和 SYNCHRONIZE。
GENERIC_WRITE STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_APPEND_DATA 和 SYNCHRONIZE。

[in] ObjectAttributes

指向已使用 InitializeObjectAttributes初始化的不透明 OBJECT_ATTRIBUTES 结构的指针。 如果调用方在系统进程上下文中运行，则可以 NULL。 否则，调用方必须在调用 InitializeObjectAttributes中设置OBJ_KERNEL_HANDLE属性。 下表列出了文件对象的此结构的成员。

成员 价值
ULONG 长度 ObjectAttributes指向的结构中包含的数据的字节数。 此值必须至少 sizeof（OBJECT_ATTRIBUTES）。
PUNICODE_STRING ObjectName 指向 UNICODE_STRING 结构的指针，该结构包含要创建或打开的管道的名称。 此名称必须是完全限定的文件规范或设备对象的名称，除非它是相对于 RootDirectory指定的目录的文件的名称。 例如，“\Device\NamedPipe\mypipe”或“\？？\pipe\mypipe“可以是有效的文件规范。 （注意：“\？？”将“\DosDevices”替换为 Win32 对象命名空间的名称。“\DosDevices”仍然有效，但对象管理器将更快地翻译“\？？”。
HANDLE RootDirectory 对目录的可选句柄，由上述对 FltCreateFileEx2的调用获取。 如果此值 NULL，则 ObjectName成员必须是包含目标管道的完整路径的完全限定文件规范。 如果此值为非NULL，则 ObjectName 成员指定相对于此目录的管道名称。
PSECURITY_DESCRIPTOR SecurityDescriptor 要应用于管道的可选安全描述符（SECURITY_DESCRIPTOR）。 ACL 由此类安全描述符指定的 ACL 仅在创建管道时应用于管道。 如果在创建管道时 NULL 该值，则放置在管道上的 ACL 依赖于命名管道文件系统，并允许具有任何访问权限的客户端创建实例。
ULONG 属性 一组用于控制文件对象属性的标志。 如果调用方在系统进程上下文中运行，则此参数可以为零。 否则，调用方必须设置OBJ_KERNEL_HANDLE标志。 调用方还可以选择设置OBJ_CASE_INSENSITIVE标志，该标志指示名称查找代码应忽略 ObjectName 而不是执行完全匹配搜索的情况。

[out] IoStatusBlock

指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态以及有关请求的作的信息。 从 FltCreateNamedPipeFile返回时，变量 信息 成员包含以下值之一：

FILE_CREATED

FILE_OPENED

[in] ShareAccess

对调用方需要作为以下标志之一或组合的文件进行共享访问的类型。 为尽量避免共享冲突错误，请指定以下所有共享访问标志。

ShareAccess 标志 意义
FILE_SHARE_READ 可以通过其他线程调用 FltCreateNamedPipeFile打开该文件进行读取访问。
FILE_SHARE_WRITE 可以通过其他线程调用 FltCreateNamedPipeFile打开该文件进行写入访问。

[in] CreateDisposition

一个值，该值确定要执行的作，具体取决于文件是否已存在。 该值可以是下表中所述的任何值。

CreateDisposition 值 意义
FILE_CREATE 如果文件已存在，则请求失败，并且不创建或打开指定的文件。 如果没有，请创建该文件。
FILE_OPEN 如果文件已存在，请将其打开，而不是创建新文件。 如果没有，则失败请求，并且不创建新文件。
FILE_OPEN_IF 如果文件已存在，请将其打开。 如果没有，请创建该文件。

[in] CreateOptions

创建或打开管道时要应用的选项，作为以下标志的兼容组合。

CreateOptions 标志 意义
FILE_WRITE_THROUGH 将数据写入管道的系统服务、管道系统和驱动程序必须实际将数据传输到管道中，然后再考虑完成任何请求的写入作。 如果设置了 CreateOptions 标志FILE_NO_INTERMEDIATE_BUFFERING，则会自动设置此标志。
FILE_SYNCHRONOUS_IO_ALERT 管道上的所有作都是同步执行的。 代表调用方的任何等待都受到警报的过早终止。 此标志还会导致 I/O 系统维护管道位置上下文。 如果设置了此标志，还必须设置 DesiredAccess SYNCHRONIZE 标志，以便 I/O 管理器将文件对象用作同步对象。
FILE_SYNCHRONOUS_IO_NONALERT 管道上的所有作都是同步执行的。 系统等待同步 I/O 队列和完成不受警报约束。 此标志还会导致 I/O 系统维护文件位置上下文。 如果设置了此标志，还必须设置 DesiredAccess SYNCHRONIZE 标志，以便 I/O 管理器将文件对象用作同步对象。

[in] NamedPipeType

要创建的命名管道的类型。 可以是以下值之一：

价值 意义
FILE_PIPE_BYTE_STREAM_TYPE
 数据以字节流的形式写入管道。 若要使用此类型，ReadMode 不得FILE_PIPE_MESSAGE_MODE。
FILE_PIPE_MESSAGE_TYPE
 数据以消息的形式写入管道。

[in] ReadMode

从管道中读取的模式。

价值 意义
FILE_PIPE_BYTE_STREAM_MODE
 管道数据作为字节流读取。
FILE_PIPE_MESSAGE_MODE
 管道数据作为消息进行读取。 若要使用此模式，NamedPipeType 必须FILE_PIPE_MESSAGE_TYPE。

[in] CompletionMode

管道读取和写入的完成模式。

价值 意义
FILE_PIPE_QUEUE_OPERATION
 管道读取和写入请求已排队，可以阻止直到完成。
FILE_PIPE_COMPLETE_OPERATION
 管道读取和写入请求将立即完成。

[in] MaximumInstances

此命名管道允许的最大实例数。

InboundQuota

要为输入缓冲区保留的字节数。

OutboundQuota

要为输出缓冲区保留的字节数。

[in, optional] DefaultTimeout

默认超时（以 100 纳秒为单位）。 此值表示为负整数。 例如，将 250 毫秒指定为 –10 * 1000 * 250。

[in, optional] DriverContext

指向 IoInitializeDriverCreateContext初始化的 IO_DRIVER_CREATE_CONTEXT 结构的可选指针。

返回值

FltCreateNamedPipeFile 返回STATUS_SUCCESS或适当的 NTSTATUS 值，例如以下值之一。

返回代码 描述
STATUS_FLT_DELETING_OBJECT
 Filter 或 Instance 参数中指定的筛选器或实例正在被拆毁。 如果打开的请求跨越卷装入点，并且 实例 参数为非NULL，则可以接收此状态代码。 这是一个错误代码。
STATUS_OBJECT_PATH_SYNTAX_BAD
 ObjectAttributes 参数不包含 RootDirectory 成员，但OBJECT_ATTRIBUTES结构中的 ObjectName 成员是空字符串或不包含OBJECT_NAME_PATH_SEPARATOR字符。 此错误代码指示对象路径的语法不正确。

言论

FltCreateNamedPipeFile 函数允许微型筛选器驱动程序创建或打开管道实例。 这对于创建虚拟管道或为多路复用 I/O 创建管道联合非常有用。

实例 参数是 NULL，也可以是通过附加到命名管道卷来设置的。 通过将“\Device\NamedPipe”作为卷名称传递给 FltGetVolumeFromName来获取卷指针。

若要将额外的创建参数（ECP）指定为创建作的一部分，请使用 FltAllocateExtraCreateParameterList 例程初始化 IO_DRIVER_CREATE_CONTEXT 结构的 ExtraCreateParameter 成员。 如果使用 ECP，则必须使用其关联的支持例程来分配、初始化和释放它们。 从 FltCreateNamedPipeFile的调用返回后，ECP 列表保持不变，并且可以传递给其他创建作的 FltCreateNamedPipeFile 的其他调用。 ECP 列表结构不会自动解除分配。 FltCreateNamedPipeFile 的调用方必须通过调用 FltFreeExtraCreateParameterList 例程解除分配此结构。

如果 实例 未 NULL，则来自 FltCreateNamedPipeFile 的创建请求仅发送到附加到指定微型筛选器驱动程序实例和命名管道文件系统的实例。 上面附加的指定实例和实例不会收到创建请求。 如果未指定任何实例，则请求将转到堆栈顶部，并由所有实例和命名管道文件系统接收。

要求

要求 价值
最低支持的客户端 在 Windows 8 中可用。
目标平台 普遍
标头 fltkernel.h （包括 FltKernel.h）
库 Fltmgr.lib
IRQL PASSIVE_LEVEL

另请参阅

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext