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

Статья
07/16/2024

FltCreateCommunicationPort создает порт сервера связи, на котором минифильтр может получать запросы на подключение от приложений и служб в режиме пользователя.

Синтаксис

NTSTATUS FLTAPI FltCreateCommunicationPort(
  PFLT_FILTER            Filter,
  PFLT_PORT              *ServerPort,
  POBJECT_ATTRIBUTES     ObjectAttributes,
  PVOID                  ServerPortCookie,
  PFLT_CONNECT_NOTIFY    ConnectNotifyCallback,
  PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
  PFLT_MESSAGE_NOTIFY    MessageNotifyCallback,
  LONG                   MaxConnections
);

Параметры

Filter

[in] Непрозрачный указатель фильтра для вызывающего объекта.

ServerPort

[out] Указатель на выделенную вызывающим переменную, которая получает непрозрачный дескриптор порта для порта сервера коммуникации. Минифильтр использует этот дескриптор для прослушивания входящих запросов на подключение из приложения пользовательского режима.

ObjectAttributes

[in] Указатель на структуру OBJECT_ATTRIBUTES, указывающую атрибуты порта сервера коммуникации. Эта структура должна быть инициализирована предыдущим вызовом InitializeObjectAttributes. Этот параметр является обязательным и не может иметь значение NULL. Члены этой структуры для объекта порта связи включают следующие элементы.

Член	Ценность
длина	InitializeObjectAttributes задает этому элементу значение `sizeof(OBJECT_ATTRIBUTES)`.
ObjectName	Указатель на структуру UNICODE_STRING, содержащую уникальное имя (например, L"\MyFilterPort") для объекта порта.
SecurityDescriptor	Указатель на дескриптор безопасности (SECURITY_DESCRIPTOR) для применения к объекту порта. При необходимости можно создать дескриптор безопасности по умолчанию, вызвав FltBuildDefaultSecurityDescriptor.
атрибутов	Битовая маска флагов, указывающая нужные атрибуты для дескриптора порта. Эти флаги должны содержать OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имен должен игнорировать регистр ObjectName вместо выполнения поиска точного соответствия.

ServerPortCookie

[in, необязательный] Указатель на сведения о контексте, определенные мини-фильтром. Эти сведения можно использовать для различения нескольких портов сервера связи, созданных одним минифильтром. FltMgr передает этот указатель контекста в качестве параметра в подпрограмму ConnectNotifyCallback. Этот параметр является необязательным и может иметь значение NULL.

ConnectNotifyCallback

[in] Указатель на подпрограмму обратного вызова, предоставленного вызывающим ConnectNotifyCallback. FltMgr вызывает эту подпрограмму, когда приложение в режиме пользователя вызывает FilterConnectCommunicationPort для отправки запроса на подключение к мини-фильтру. Этот параметр является обязательным и не может иметь значение NULL.

DisconnectNotifyCallback

[in] Указатель на предоставленный вызывающим DisconnectNotifyCallback подпрограмме обратного вызова. FltMgr вызывает эту подпрограмму всякий раз, когда число дескрипторов пользовательского режима для клиентского порта достигает нуля или когда мини-фильтр будет выгружен. Этот параметр является обязательным и не может иметь значение NULL.

MessageNotifyCallback

[in, необязательный] Указатель на подпрограмму обратного вызова, предоставленного вызывающим MessageNotifyCallback обратного вызова. FltMgr вызывает эту подпрограмму, когда приложение в режиме пользователя вызывает FilterSendMessage, чтобы отправить сообщение мини-фильтру через клиентский порт. Этот параметр является необязательным и может иметь значение NULL. Если значение NULL, любой запрос, сделанный в пользовательском режиме для отправки данных в порт, получает ошибку.

MaxConnections

[in] Максимальное число одновременных подключений клиента, разрешенных для этого порта сервера. Этот параметр является обязательным и должен быть больше нуля.

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

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

Возвращаемый код	Описание
STATUS_FLT_DELETING_OBJECT	Указанный фильтр отключается. Это код ошибки.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort возникла ошибка выделения пула. Это код ошибки.
STATUS_OBJECT_NAME_COLLISION	Порт связи с тем же именем уже существует. Имена портов должны быть уникальными. Это код ошибки.

Замечания

Минифильтр вызывает FltCreateCommunicationPort для создания объекта порта сервера коммуникации.

После создания порта сервера приложение пользовательского режима может подключиться к порту, вызвав FilterConnectCommunicationPort. При подключении приложение пользовательского режима может отправлять и получать сообщения, вызывая функции обмена сообщениями в режиме пользователя, такие как FilterSendMessage, FilterGetMessageи FilterReplyMessage.

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

Любой порт сервера, который FltCreateCommunicationPort, должен быть закрыт путем вызова FltCloseCommunicationPort. При закрытии порта сервера новые подключения к порту сервера не допускаются, и все вызовы FilterConnectCommunicationPort сбой. Однако все существующие подключения остаются открытыми до тех пор, пока они не будут закрыты приложением пользовательского режима или минифильтром, или до тех пор, пока мини-фильтр не выгрузится.

Дополнительные сведения см. в разделе Обмен данными между пользовательским режимом и минифильтрами.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h)
библиотеки	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL