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 标志。 有关其他信息，请参阅 FltCreateFileEx2 的 FileAttributes 参数中的有效标志值表。 |
| READ_CONTROL | 可以读取与命名管道关联的访问控制列表 (ACL) 和所有权信息。 |
| FILE_WRITE_DATA | 数据可以写入命名管道。 |
| FILE_WRITE_ATTRIBUTES | 可以写入 FileAttributes 标志。 |
| FILE_APPEND_DATA | 可将数据追加到文件。 |
| WRITE_DAC | 可以写入与命名管道关联的自由访问控制列表 (DACL) 。 |
| WRITE_OWNER | 可以写入与命名管道关联的所有权信息。 |
| ACCESS_SYSTEM_SECURITY | 调用方将具有对命名管道的 SACL 的写入访问权限 |
| SYNCHRONIZE | 调用方可以通过等待返回的 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 属性。 下表列出了文件对象的此结构的成员。
| 成员 | Value |
|---|---|
| ULONG 长度 | ObjectAttributes 指向的结构中包含的数据的字节数。 此值的大小必须至少 为 (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 仅在创建管道时应用于管道。 如果创建管道时该值为 NULL ，则放置在管道上的 ACL 依赖于命名管道文件系统，并且可能允许具有任何访问权限的客户端创建实例。 |
| ULONG 属性 | 一组控制文件对象属性的标志。 如果调用方在系统进程上下文中运行，则此参数可以为零。 否则，调用方必须设置OBJ_KERNEL_HANDLE标志。 调用方还可以选择性地设置OBJ_CASE_INSENSITIVE标志，该标志指示名称查找代码应忽略 ObjectName 大小写，而不是执行完全匹配的搜索。 |
[out] IoStatusBlock
指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态和有关所请求操作的信息。 从 FltCreateNamedPipeFile 返回时，变量的 Information 成员包含以下值之一：
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_MESSAGE_MODE ReadMode 。 |
|
数据作为消息写入管道。 |
[in] ReadMode
要从管道读取的模式。
| 值 | 含义 |
|---|---|
|
管道数据作为字节流读取。 |
|
管道数据作为消息读取。 若要使用此模式，必须FILE_PIPE_MESSAGE_TYPE NamedPipeType 。 |
[in] CompletionMode
管道读取和写入的完成模式。
| 值 | 含义 |
|---|---|
|
管道读取和写入请求已排队，可以阻止，直到完成。 |
|
管道读取和写入请求将立即完成。 |
[in] MaximumInstances
此命名管道允许的最大实例数。
InboundQuota
要为输入缓冲区保留的字节数。
OutboundQuota
要为输出缓冲区保留的字节数。
[in, optional] DefaultTimeout
以 100 纳秒为增量的默认超时。 此值表示为负整数。 例如，250 毫秒指定为 –10 * 1000 * 250。
[in, optional] DriverContext
指向 IoInitializeDriverCreateContext 已初始化的IO_DRIVER_CREATE_CONTEXT结构的可选指针。
返回值
FltCreateNamedPipeFile 返回STATUS_SUCCESS或相应的 NTSTATUS 值，如以下值之一。
| 返回代码 | 说明 |
|---|---|
|
正在拆除 Filter 或 Instance 参数中指定的 筛选器 或 实例 。 如果打开的请求跨卷装入点，并且 Instance 参数为非 NULL，则可以接收此状态代码。 这是错误代码。 |
|
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 例程解除分配此结构。
如果 Instance 不为 NULL，则来自 FltCreateNamedPipeFile 的创建请求仅发送到附加到指定微筛选器驱动程序实例下方的实例和命名管道文件系统。 指定的实例和上面附加的实例不会收到创建请求。 如果未指定实例，则请求将转到堆栈顶部，并且所有实例和命名管道文件系统都会收到请求。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 Windows 8 中可用。 |
| 目标平台 | 通用 |
| 标头 | fltkernel.h (包括 FltKernel.h) |
| Library | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
另请参阅
FltAllocateExtraCreateParameterList