Функция FltCreateMailslotFile (fltkernel.h)
Драйверы мини-фильтра вызывают 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 можно считать. Дополнительные сведения см. в таблице допустимых значений флагов в параметре FileAttributesобъекта FltCreateFileEx2. |
| READ_CONTROL | Список управления доступом список управления доступом и сведения о владельце, связанные с mailslot, можно считать. |
| FILE_WRITE_DATA | Данные могут быть записаны в почтовый слой. |
| FILE_WRITE_ATTRIBUTES | Можно записывать флаги FileAttributes. |
| FILE_APPEND_DATA | К почтовому слою можно добавить данные. |
| WRITE_DAC | Можно написать список управления доступом на уровне пользователей , связанный с почтовым слоем. |
| WRITE_OWNER | Можно записать сведения о владельцах, связанных с почтовым слоем. |
| ACCESS_SYSTEM_SECURITY | Вызывающий объект будет иметь доступ на запись к SACL почтового объекта mailslot. |
| SYNCHRONIZE | Вызывающий объект может синхронизировать завершение операции ввода-вывода, ожидая, пока возвращенное значение FileHandle будет установлено в состояние Signaled. Этот флаг необходимо задать, если установлен флаг 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
Указатель на непрозрачную структуру OBJECT_ATTRIBUTES , которая уже инициализирована с помощью атрибутов InitializeObjectAttributes. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может иметь значение NULL. В противном случае вызывающий объект должен задать атрибут OBJ_KERNEL_HANDLE в вызове InitializeObjectAttributes. Элементы этой структуры для объекта файла перечислены в следующей таблице.
| Член | Значение |
|---|---|
| Длина ULONG | Количество байтов данных, содержащихся в структуре, на которую указывает ObjectAttributes. Это значение должно быть не менее sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Указатель на структуру UNICODE_STRING , содержащую имя создаваемого или открываемого почтового слоя. Это имя должно быть полной спецификацией файла или именем объекта устройства, если оно не является именем файла относительно каталога, указанного в RootDirectory. Например, "\Device\Mailslot\myslot" или "?? \mailslot\myslot" может быть допустимыми спецификациями файлов. (Примечание. "??" заменяет "\DosDevices" в качестве имени пространства имен объекта Win32. "\DosDevices" по-прежнему работает, но "??" преобразуется быстрее диспетчером объектов. |
| HANDLE RootDirectory | Необязательный дескриптор для каталога, полученный при предыдущем вызове FltCreateFileEx2. Если это значение равно NULL, элемент ObjectName должен быть полной спецификацией файла, которая включает полный путь к целевому почтовому слою. Если это значение не равно NULL, элемент ObjectName указывает имя почтового объекта относительно этого каталога. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Необязательный SECURITY_DESCRIPTOR , применяемый к почтовому слою. Списки управления доступом , заданные таким дескриптором безопасности, применяются только к созданному почтовому слою. Если при создании mailslot значение равно NULL , список управления доступом, размещенный в mailslot, зависит от файловой системы mailslot и может разрешить клиенту с любым доступом создать экземпляр. |
| Атрибуты ULONG | Набор флагов, управляющий атрибутами объекта файла. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может быть равен нулю. В противном случае вызывающий объект должен установить флаг OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имени должен игнорировать регистр ObjectName , а не выполнять поиск точного соответствия. |
[out] IoStatusBlock
Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения о запрошенной операции. При возвращении из FltCreateMailslotFile элемент Information переменной содержит одно из следующих значений:
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
Параметры, применяемые при создании или открытии почтового объекта, в виде совместимого сочетания следующих флагов.
| Флаги | Значение |
|---|---|
| FILE_WRITE_THROUGH | Системные службы, файловые системы и драйверы, которые записывают данные в mailslot, должны фактически передавать данные в mailslot, прежде чем любая запрошенная операция записи будет считаться завершенной. Этот флаг устанавливается автоматически, если установлен флаг CreateOptions FILE_NO_INTERMEDIATE_BUFFERING. |
| FILE_SYNCHRONOUS_IO_ALERT | Все операции с mailslot выполняются синхронно. Любое ожидание от имени звонящего зависит от преждевременного завершения оповещений. Этот флаг также приводит к тому, что система ввода-вывода будет поддерживать контекст позиции почтового объекта. Если этот флаг установлен, необходимо также установить флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект file в качестве объекта синхронизации. |
| FILE_SYNCHRONOUS_IO_NONALERT | Все операции с mailslot выполняются синхронно. Ожидания в системе для синхронизации очередей и завершения ввода-вывода не распространяются на оповещения. Этот флаг также приводит к тому, что система ввода-вывода будет поддерживать контекст позиции файла. Если этот флаг установлен, необходимо также установить флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект file в качестве объекта синхронизации. |
[in] MailslotQuota
Размер (в байтах) буфера для операций записи в mailslot.
[in] MaximumMessageSize
Максимальный размер (в байтах) сообщения для записи в почтовый объект. Сообщение любого размера указывается значением 0.
[in] ReadTimeout
Время, когда операция чтения ожидает, пока сообщение будет доступно в почтовом слою. Время ожидания по умолчанию выражается в 100-наносекундных приращениях в виде отрицательного целого числа. Например, 250 миллисекундам задано как –10*1000*250. Кроме того, следующие значения имеют особые значения.
| Значение | Значение |
|---|---|
| 0 | Возвращает немедленно, если сообщение отсутствует. |
| -1 | Вечное ожидание сообщения. |
[in, optional] DriverContext
Необязательный указатель на структуру IO_DRIVER_CREATE_CONTEXT , уже инициализированную IoInitializeDriverCreateContext.
Возвращаемое значение
FltCreateMailslotFile возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений.
| Код возврата | Описание |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Фильтр или экземпляр, указанный в параметрах Фильтра или Экземпляра , будет снесен. Этот код состояния можно получить, если открытый запрос пересекает точку подключения тома, а параметр Instance имеет значение, отличное от NULL. Это код ошибки. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | Параметр ObjectAttributes не содержал элемента RootDirectory , но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символа OBJECT_NAME_PATH_SEPARATOR. Этот код ошибки указывает на неправильный синтаксис пути к объекту. |
Комментарии
Функция FltCreateMailslotFile позволяет драйверам минифильтра создавать или открывать экземпляры mailslot. Это полезно для создания виртуальных почтовых слоотов или для создания группы mailslots, которая распространяется на несколько других почтовых слоотов.
Параметр Instance имеет значение NULL или задается ранее путем вложения в том почтового объекта. Указатель тома получается путем передачи "\Device\Mailslot" в качестве имени тома в FltGetVolumeFromName.
Чтобы указать дополнительный параметр создания (ECP) в рамках операции создания, инициализируйте элемент ExtraCreateParameter структуры IO_DRIVER_CREATE_CONTEXT с помощью процедуры FltAllocateExtraCreateParameterList . Если используются ECP, их необходимо выделить, инициализировать и освободить с помощью связанных процедур поддержки. После возвращения из вызова FltCreateMailslotFile список ECP не изменяется и может передаваться в дополнительные вызовы FltCreateMailslotFile для других операций создания. Структура списка ECP не освобождается автоматически. Вызывающий объект FltCreateMailslotFile должен освободить эту структуру, вызвав подпрограмму FltFreeExtraCreateParameterList .
Если параметр Instance не имеет значение NULL, запрос на создание из FltCreateMailslotFile отправляется только экземплярам, подключенным под указанным экземпляром драйвера минифильтра, и в файловую систему mailslot. Указанный экземпляр и экземпляры, присоединенные над ним, не получают запрос на создание. Если экземпляр не указан, запрос направляется в верхнюю часть стека и получается всеми экземплярами и файловой системой mailslot.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно в Windows 8. |
| Целевая платформа | Универсальное |
| Верхняя часть | fltkernel.h (включая FltKernel.h) |
| Библиотека | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
См. также раздел
FltAllocateExtraCreateParameterList