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 标志。 有关详细信息，请参阅 FileAttributesFltCreateFileEx2参数中的有效标志值表。 |
| 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 具有写入访问权限。 |
| 同步 | 调用方可以通过等待返回 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\Mailslot\myslot”或“？？\mailslot\myslot“可以是有效的文件规范。 （注意：“？？”将“\DosDevices”替换为 Win32 对象命名空间的名称。 “\DosDevices”仍然有效，但对象管理器将更快地翻译“？？”。 |
| HANDLE RootDirectory | 目录的可选句柄，由上述对 FltCreateFileEx2的调用获取。 如果此值 NULL，则 ObjectName 成员必须是包含目标 mailslot 的完整路径的完全限定文件规范。 如果此值为非NULL，则 ObjectName 成员指定相对于此目录的邮件图名称。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | 要应用于 mailslot 的可选 SECURITY_DESCRIPTOR。 ACL 由此类安全描述符指定的 ACL 仅应用于创建 mailslot 时。 如果在创建 mailslot 时 NULL 该值，则放置在 mailslot 上的 ACL 依赖于 mailslot 文件系统，并允许具有任何访问权限的客户端创建实例。 |
| ULONG 属性 | 一组用于控制文件对象属性的标志。 如果调用方在系统进程上下文中运行，则此参数可以为零。 否则，调用方必须设置OBJ_KERNEL_HANDLE标志。 调用方还可以选择设置OBJ_CASE_INSENSITIVE标志，该标志指示名称查找代码应忽略 ObjectName 而不是执行完全匹配搜索的情况。 |
[out] IoStatusBlock
指向接收最终完成状态和所请求作信息的 IO_STATUS_BLOCK 结构的指针。 从 FltCreateMailslotFile返回时，变量 信息 成员包含以下值之一：
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
创建或打开 mailslot 时要应用的选项，作为以下标志的兼容组合。
| 标志 | 意义 |
|---|---|
| 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 参数中指定的筛选器或实例正在被拆毁。 如果打开的请求跨越卷装入点，并且 实例 参数为非NULL，则可以接收此状态代码。 这是一个错误代码。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD | ObjectAttributes 参数不包含 RootDirectory 成员，但OBJECT_ATTRIBUTES结构中的 ObjectName 成员是空字符串或不包含OBJECT_NAME_PATH_SEPARATOR字符。 此错误代码指示对象路径的语法不正确。 |
言论
FltCreateMailslotFile 函数允许微型筛选驱动程序创建或打开 mailslot 实例。 这对于创建虚拟 mailslots 或创建可分发到其他几个 mailslots 的 mailslot 组非常有用。
实例 参数是 NULL，或者以前通过附加到 mailslot 卷来设置。 通过将“\Device\Mailslot”作为卷名称传递给 FltGetVolumeFromName来获取卷指针。
若要将额外的创建参数 （ECP） 指定为创建作的一部分，请使用 FltAllocateExtraCreateParameterList 例程初始化 IO_DRIVER_CREATE_CONTEXT 结构的 ExtraCreateParameter 成员。 如果使用 ECP，则必须使用其关联的支持例程来分配、初始化和释放它们。 从 FltCreateMailslotFile的调用返回后，ECP 列表保持不变，并可能传递给其他创建作的 FltCreateMailslotFile 调用。 ECP 列表结构不会自动解除分配。 FltCreateMailslotFile 的调用方必须通过调用 FltFreeExtraCreateParameterList 例程解除分配此结构。
如果 实例 未 NULL，则从 FltCreateMailslotFile 创建请求仅发送到附加到指定微型筛选器驱动程序实例和 mailslot 文件系统下方的实例。 上面附加的指定实例和实例不会收到创建请求。 如果未指定实例，则请求将转到堆栈的顶部，并由所有实例和 mailslot 文件系统接收。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | 在 Windows 8 中可用。 |
| 目标平台 | 普遍 |
| 标头 | fltkernel.h （包括 FltKernel.h） |
| 库 | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
另请参阅
FltAllocateExtraCreateParameterList