FltCreateMailslotFile 函数 (fltkernel.h)
微筛选器驱动程序调用 FltCreateMailslotFile 以创建新管道或打开现有 mailslot。
语法
NTSTATUS FLTAPI FltCreateMailslotFile(
[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 CreateOptions,
[in] ULONG MailslotQuota,
[in] ULONG MaximumMessageSize,
[in] PLARGE_INTEGER ReadTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
参数
[in] Filter
调用方不透明的筛选器指针。
[in, optional] Instance
创建请求要发送到的微筛选器驱动程序实例的不透明实例指针。 实例必须附加到 mailslot 文件系统的卷。 此参数是可选的，可以为 NULL。 如果此参数为 NULL，则请求将发送到卷的文件系统驱动程序堆栈顶部的设备对象。 如果为非 NULL，则请求仅发送到附加到指定实例下方的微型筛选器驱动程序实例。
[out] FileHandle
指向调用方分配的变量的指针，如果对 FltCreateMailslotFile 的调用成功，该变量接收文件句柄。
[out, optional] FileObject
指向调用方分配的变量的指针，如果对 FltCreateMailslotFile 的调用成功，该变量将接收文件对象指针。 此参数是可选的，可以为 NULL。
[in] DesiredAccess
标志的位掩码，指定调用方需要对文件或目录的访问类型。 系统定义的 DesiredAccess 标志集确定文件对象的以下特定访问权限。
| DesiredAccess 标志 | 含义 |
|---|---|
| FILE_READ_DATA | 可以从命名的 mailslot 读取数据。 |
| FILE_READ_ATTRIBUTES | 可以读取 FileAttributes 标志。 有关其他信息，请参阅 FltCreateFileEx2 的 FileAttributes 参数中的有效标志值表。 |
| READ_CONTROL | 可以读取与 mailslot 关联的访问控制列表 ACL 和所有权信息。 |
| FILE_WRITE_DATA | 可将数据写入 mailslot。 |
| FILE_WRITE_ATTRIBUTES | 可以写入 FileAttributes 标志。 |
| FILE_APPEND_DATA | 可将数据追加到 mailslot。 |
| WRITE_DAC | 可以编写与 mailslot 关联的任意访问控制列表 DACL 。 |
| WRITE_OWNER | 可以编写与 mailslot 关联的所有权信息。 |
| ACCESS_SYSTEM_SECURITY | 调用方将具有对 mailslot 的 SACL 的写入访问权限。 |
| SYNCHRONIZE | 调用方可以通过等待返回的 FileHandle 设置为“已信号”状态来同步 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 指向的结构中包含的数据的字节数。 此值必须至少 sizeof(OBJECT_ATTRIBUTES)为 。 |
| PUNICODE_STRING ObjectName | 指向 UNICODE_STRING 结构的指针，该结构包含要创建或打开的邮件图的名称。 此名称必须是完全限定的文件规范或设备对象的名称，除非它是相对于 RootDirectory 指定的目录的文件的名称。 例如，“\Device\Mailslot\myslot”或“？？\mailslot\myslot“ 都可以是有效的文件规范。 (注意：“？？”将“\DosDevices”替换为 Win32 对象命名空间的名称。 “\DosDevices”仍然有效，但“？？”被对象管理器更快地转换。 |
| HANDLE RootDirectory | 目录的可选句柄，由前面对 FltCreateFileEx2 的调用获取。 如果此值为 NULL， 则 ObjectName 成员必须是包含目标 mailslot 的完整路径的完全限定文件规范。 如果此值为非 NULL， 则 ObjectName 成员指定相对于此目录的邮件图名称。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | 要应用于 mailslot 的可选SECURITY_DESCRIPTOR 。 此类安全描述符指定的 ACL 仅在创建邮件图时应用于邮件图。 如果在创建 mailslot 时该值为 NULL ，则 mailslot 上放置的 ACL 依赖于 mailslot 文件系统，并且可能允许具有任何访问权限的客户端创建实例。 |
| ULONG 属性 | 一组控制文件对象属性的标志。 如果调用方在系统进程上下文中运行，则此参数可以为零。 否则，调用方必须设置OBJ_KERNEL_HANDLE标志。 调用方还可以选择性地设置OBJ_CASE_INSENSITIVE标志，该标志指示名称查找代码应忽略 ObjectName 的事例，而不是执行完全匹配的搜索。 |
[out] IoStatusBlock
指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态和有关所请求操作的信息。 从 FltCreateMailslotFile 返回时，变量 的 Information 成员包含以下值之一：
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
创建或打开 mailslot 时要应用的选项，作为以下标志的兼容组合。
| Flags | 含义 |
|---|---|
| FILE_WRITE_THROUGH | 将数据写入 mailslot 的系统服务、文件系统和驱动程序必须实际将数据传输到 mailslot，然后才能将请求的任何写入操作视为完成。 如果设置了 CreateOptions 标志FILE_NO_INTERMEDIATE_BUFFERING，则会自动设置此标志。 |
| FILE_SYNCHRONOUS_IO_ALERT | mailslot 上的所有操作都是同步执行的。 代表调用方的任何等待都可能提前终止警报。 此标志还会导致 I/O 系统维护 mailslot 位置上下文。 如果设置了此标志，还必须设置 DesiredAccess SYNCHRONIZE 标志，以便 I/O 管理器将文件对象用作同步对象。 |
| FILE_SYNCHRONOUS_IO_NONALERT | mailslot 上的所有操作都是同步执行的。 在系统中等待同步 I/O 队列和完成不受警报约束。 此标志还会导致 I/O 系统维护文件位置上下文。 如果设置了此标志，还必须设置 DesiredAccess SYNCHRONIZE 标志，以便 I/O 管理器将文件对象用作同步对象。 |
[in] MailslotQuota
写入 mailslot 的缓冲区的大小（以字节为单位）。
[in] MaximumMessageSize
要写入 mailslot 的邮件的最大大小（以字节为单位）。 任何大小的消息都由值 0 指定。
[in] ReadTimeout
读取操作等待邮件在 mailslot 中可用的时间。 默认超时以 100 纳秒的增量表示为负整数。 例如，250 毫秒指定为 –10*1000*250。 此外，以下值具有特殊含义。
| 值 | 含义 |
|---|---|
| 0 | 如果没有消息，则立即返回 。 |
| -1 | 永远等待消息。 |
[in, optional] DriverContext
指向 IoInitializeDriverCreateContext 已初始化的 IO_DRIVER_CREATE_CONTEXT 结构的可选指针。
返回值
FltCreateMailslotFile 返回STATUS_SUCCESS或相应的 NTSTATUS 值，例如以下值之一。
| 返回代码 | 说明 |
|---|---|
| STATUS_FLT_DELETING_OBJECT | 正在拆除 Filter 或 Instance 参数中指定的 筛选器 或 实例 。 如果打开的请求跨越卷装入点，并且 Instance 参数为非 NULL，则可以接收此状态代码。 这是错误代码。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD | ObjectAttributes 参数不包含 RootDirectory 成员，但 OBJECT_ATTRIBUTES 结构中的 ObjectName 成员是空字符串或不包含OBJECT_NAME_PATH_SEPARATOR字符。 此错误代码指示对象路径的语法不正确。 |
注解
FltCreateMailslotFile 函数允许微筛选器驱动程序创建或打开 mailslot 实例。 这对于创建虚拟 mailslot 或创建分发到其他几个 mailslot 的 mailslot 组非常有用。
Instance 参数为 NULL，或者以前通过附加到 mailslot 卷进行设置。 通过将“\Device\Mailslot”作为卷名传递给 FltGetVolumeFromName 来获取卷指针。
若要在创建操作过程中 (ECP) 指定额外的创建参数，请使用 FltAllocateExtraCreateParameterList 例程初始化 IO_DRIVER_CREATE_CONTEXT 结构的 ExtraCreateParameter 成员。 如果使用 ECP，则必须使用其关联的支持例程来分配、初始化和释放它们。 从 FltCreateMailslotFile 的调用返回后，ECP 列表将保持不变，并可能传递给 FltCreateMailslotFile 的其他调用，以便执行其他创建操作。 ECP 列表结构不会自动解除分配。 FltCreateMailslotFile 的调用方必须通过调用 FltFreeExtraCreateParameterList 例程解除分配此结构。
如果 Instance 不为 NULL，则来自 FltCreateMailslotFile 的 创建请求仅发送到指定微筛选器驱动程序实例下方附加的实例和 mailslot 文件系统。 指定的实例和上面附加的实例不会收到创建请求。 如果未指定实例，则请求将转到堆栈顶部，并由所有实例和 mailslot 文件系统接收。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 Windows 8 中可用。 |
| 目标平台 | 通用 |
| 标头 | fltkernel.h (包括 FltKernel.h) |
| Library | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
另请参阅
FltAllocateExtraCreateParameterList