Функция FltCreateMailslotFile (fltkernel.h)

Статья
02/06/2025

Драйверы минифильтра вызывают вызов FltCreateMailslotFile для создания канала или открытия существующего почтового объекта.

Синтаксис

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	Данные можно считывать из именованного почтового потока.
FILE_READ_ATTRIBUTES	флаги FileAttributes можно считывать. Дополнительные сведения см. в таблице допустимых значений флагов в параметре FileAttributesFltCreateFileEx2.
READ_CONTROL	Список управления доступом ACL и сведения о собственности, связанные с mailslot, можно считывать.
FILE_WRITE_DATA	Данные можно записать в mailslot.
FILE_WRITE_ATTRIBUTES	флаги FileAttributes можно записать.
FILE_APPEND_DATA	Данные можно добавить в mailslot.
WRITE_DAC	Список управления доступом по усмотрению DACL, связанный с mailslot, можно записать.
WRITE_OWNER	Сведения о собственности, связанные с mailslot, можно написать.
ACCESS_SYSTEM_SECURITY	Вызывающий объект будет иметь доступ на запись к SACL почтового объекта mailslot.
СИНХРОНИЗИРОВАТЬ	Вызывающий объект может синхронизировать завершение операции ввода-вывода, ожидая, пока возвращенный FileHandle будет задано состояние Signaled. Этот флаг необходимо задать, если установлен флаг CreateOptions FILE_SYNCHRONOUS_IO_ALERT или флаг FILE_SYNCHRONOUS_IO_NONALERT.

Кроме того, для любого объекта файла, который не представляет каталог, можно указать один или несколько следующих универсальных флагов ACCESS_MASK. (Флаги STANDARD_RIGHTS_XXX являются предопределенными системными значениями, которые используются для обеспечения безопасности системных объектов.) Вы также можете объединить эти универсальные флаги с дополнительными флагами из предыдущей таблицы.

DesiredAccess to File Values	Карты с флагами DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA и СИНХРОНИЗИРОВАТЬ.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA и СИНХРОНИЗИРОВАТЬ.

[in] ObjectAttributes

Указатель на непрозрачную структуру OBJECT_ATTRIBUTES, которая уже инициализирована с помощью InitializeObjectAttributes. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может быть NULL. В противном случае вызывающий объект должен задать атрибут OBJ_KERNEL_HANDLE в вызове InitializeObjectAttributes. Элементы этой структуры для объекта файла перечислены в следующей таблице.

Член	Ценность
длина ULONG	Количество байтов данных, содержащихся в структуре, на которые указывает ObjectAttributes. Это значение должно быть по крайней мере `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Указатель на структуру UNICODE_STRING, содержащую имя файла mailslot, который нужно создать или открыть. Это имя должно быть полной спецификацией файла или именем объекта устройства, если он не является именем файла относительно каталога, указанного RootDirectory. Например, "\Device\Mailslot\myslot" или "?? \mailslot\myslot" может быть допустимыми спецификациями файлов. (Примечание. "??" заменяет "\DosDevices" в качестве имени пространства имен объектов Win32. "\DosDevices" по-прежнему работает, но "??" преобразуется быстрее диспетчером объектов.
HANDLE RootDirectory	Необязательный дескриптор каталога, полученный при предыдущем вызове FltCreateFileEx2. Если это значение равно NULL, элемент ObjectName должен быть полной спецификацией файла, которая включает полный путь к целевому почтовому слою. Если это значение не являетсяNULL, элемент objectName указывает имя почтового канала, которое относительно этого каталога.
securityDescriptor PSECURITY_DESCRIPTOR	Необязательный SECURITY_DESCRIPTOR применяться к почтовому слоту. списки управления доступом, указанные таким дескриптором безопасности, применяются только к mailslot при его создании. Если значение NULL при создании почтового объекта, ACL, помещенный в mailslot, зависит от файловой системы mailslot и может разрешить клиенту доступ к созданию экземпляра.
атрибуты ULONG	Набор флагов, которые управляют атрибутами объекта файла. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может быть равен нулю. В противном случае вызывающий объект должен задать флаг OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имен должен игнорировать регистр ObjectName вместо выполнения поиска точного соответствия.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK, которая получает окончательное состояние завершения и сведения о запрошенной операции. При возвращении из FltCreateMailslotFileэлемент Information переменной содержит одно из следующих значений:

FILE_CREATED
FILE_OPENED

[in] CreateOptions

Параметры, применяемые при создании или открытии mailslot, в качестве совместимого сочетания следующих флагов.

Флаги	Значение
FILE_WRITE_THROUGH	Системные службы, файловые системы и драйверы, которые записывают данные в mailslot, должны фактически передавать данные в mailslot, прежде чем любая запрошенная операция записи считается завершенной. Этот FILE_NO_INTERMEDIATE_BUFFERING флаг устанавливается автоматически, если установлен флаг CreateOptions.
FILE_SYNCHRONOUS_IO_ALERT	Все операции с mailslot выполняются синхронно. Любое ожидание от имени вызывающего абонента подлежит преждевременному прекращению от оповещений. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст позиции mailslot. Если этот флаг задан, необходимо также задать флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект файла в качестве объекта синхронизации.
FILE_SYNCHRONOUS_IO_NONALERT	Все операции с mailslot выполняются синхронно. Ожидание синхронизации очереди ввода-вывода и завершения в системе не распространяется на оповещения. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст положения файла. Если этот флаг задан, необходимо также задать флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект файла в качестве объекта синхронизации.

[in] MailslotQuota

Размер буфера в байтах для записи в mailslot.

[in] MaximumMessageSize

Максимальный размер сообщения в байтах для записи в mailslot. Сообщение любого размера указывается значением 0.

[in] ReadTimeout

Время операции чтения ожидает доступности сообщения в mailslot. Время ожидания по умолчанию выражается в 100-наносекундах в виде отрицательного целого числа. Например, 250 миллисекунда указывается как –10*1000*250. Кроме того, следующие значения имеют особые значения.

Ценность	Значение
0	Возвращается немедленно, если сообщение отсутствует.
-1	Ожидание сообщения навсегда.

[in, optional] DriverContext

Необязательный указатель на структуру IO_DRIVER_CREATE_CONTEXT, уже инициализируемую IoInitializeDriverCreateContext.

Возвращаемое значение

FltCreateMailslotFile возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений.

Возвращаемый код	Описание
STATUS_FLT_DELETING_OBJECT	Фильтр или экземпляр, указанный в параметрах фильтра или экземпляра, отключается. Этот код состояния можно получить, если открытый запрос пересекает точку подключения тома, а параметр экземпляра не являетсяNULL. Это код ошибки.
STATUS_OBJECT_PATH_SYNTAX_BAD	Параметр ObjectAttributes не содержал элемента RootDirectory, но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символ OBJECT_NAME_PATH_SEPARATOR. Этот код ошибки указывает неправильный синтаксис пути к объекту.

Возвращаемый код

Описание

STATUS_FLT_DELETING_OBJECT

Фильтр или экземпляр, указанный в параметрах фильтра или экземпляра, отключается. Этот код состояния можно получить, если открытый запрос пересекает точку подключения тома, а параметр экземпляра не являетсяNULL. Это код ошибки.

STATUS_OBJECT_PATH_SYNTAX_BAD

Параметр ObjectAttributes не содержал элемента RootDirectory, но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символ OBJECT_NAME_PATH_SEPARATOR. Этот код ошибки указывает неправильный синтаксис пути к объекту.

Замечания

Функция FltCreateMailslotFile позволяет драйверам минифильтра создавать или открывать экземпляры mailslot. Это полезно для создания виртуальных почтовых слоток или для создания группы mailslot, которая распространяется на несколько других почтовых слоток.

Параметр экземпляра NULL или ранее установлен путем присоединения к тому mailslot. Указатель тома получается путем передачи "\Device\Mailslot" в качестве имени тома FltGetVolumeFromName.

Чтобы указать дополнительный параметр создания (ECP) в рамках операции создания, инициализировать элемент ExtraCreateParameter структуры IO_DRIVER_CREATE_CONTEXT с помощью подпрограммы FltAllocateExtraCreateParameterList. Если используются ЕЦП, они должны быть выделены, инициализированы и освобождены с помощью связанных подпрограмм поддержки. При возвращении из вызова FltCreateMailslotFileсписок ECP не изменяется и может передаваться в дополнительные вызовы FltCreateMailslotFile для других операций создания. Структура списка ECP не будет автоматически освобождена. Вызывающий объект FltCreateMailslotFile должен освободить эту структуру, вызвав подпрограмму FltFreeExtraCreateParameterList.

Если экземпляр не NULL, то запрос на создание из FltCreateMailslotFile отправляется только экземплярам, подключенным под указанным экземпляром драйвера минифильтра, и в файловую систему mailslot. Указанный экземпляр и экземпляры, присоединенные выше, не получают запрос на создание. Если экземпляр не указан, запрос переходит в верхнюю часть стека и получается всеми экземплярами и файловой системой mailslot.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows 8.
целевая платформа	Всеобщий
заголовка	fltkernel.h (include FltKernel.h)
библиотеки	Fltmgr.lib
IRQL	PASSIVE_LEVEL

См. также

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext

Поделиться через