Функция FltCreateCommunicationPort (fltkernel.h)
FltCreateCommunicationPort создает порт сервера связи, на котором драйвер минифильтра может получать запросы на подключение от приложений в пользовательском режиме.
Синтаксис
NTSTATUS FLTAPI FltCreateCommunicationPort(
[in] PFLT_FILTER Filter,
[out] PFLT_PORT *ServerPort,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] PVOID ServerPortCookie,
[in] PFLT_CONNECT_NOTIFY ConnectNotifyCallback,
[in] PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
[in, optional] PFLT_MESSAGE_NOTIFY MessageNotifyCallback,
[in] LONG MaxConnections
);
Параметры
[in] Filter
Непрозрачный указатель фильтра для вызывающего объекта.
[out] ServerPort
Указатель на переменную, выделенную вызывающим объектом, которая получает непрозрачный дескриптор порта для порта сервера связи. Драйвер минифильтра использует этот дескриптор для прослушивания входящих запросов на подключение от приложения в пользовательском режиме.
[in] ObjectAttributes
Указатель на структуру OBJECT_ATTRIBUTES , указывающую атрибуты порта сервера связи. Эта структура должна быть инициализирована предыдущим вызовом InitializeObjectAttributes. Этот параметр является обязательным и не может иметь значение NULL. В эту структуру для объекта порта связи входят следующие элементы.
Член | Значение |
---|---|
Длина ULONG |
InitializeObjectAttributes задает для этого элемента значение sizeof(OBJECT_ATTRIBUTES). |
PUNICODE_STRING ObjectName | Указатель на структуру UNICODE_STRING , содержащую уникальное имя (например, L"\\MyFilterPort") для объекта port. |
PSECURITY_DESCRIPTOR SecurityDescriptor | Указатель на дескриптор безопасности (SECURITY_DESCRIPTOR), применяемый к объекту порта. При необходимости можно создать дескриптор безопасности по умолчанию, вызвав FltBuildDefaultSecurityDescriptor. |
АтрибутыULONG | Битовая маска флагов, указывающих нужные атрибуты для дескриптора порта. Эти флаги должны включать OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имени должен игнорировать регистр ObjectName , а не выполнять поиск точного соответствия. |
[in, optional] ServerPortCookie
Указатель на контекстные сведения, определенные драйвером минифильтра. Эти сведения можно использовать для различения нескольких портов сервера связи, созданных одним и тем же драйвером минифильтра. Диспетчер фильтров передает этот указатель контекста в качестве параметра в подпрограмму ConnectNotifyCallback . Этот параметр является необязательным и может иметь значение NULL.
[in] ConnectNotifyCallback
Указатель на подпрограмму обратного вызова, предоставляемую вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму всякий раз, когда приложение пользовательского режима вызывает FilterConnectCommunicationPort для отправки запроса на подключение к драйверу минифильтра. Этот параметр является обязательным и не может иметь значение NULL. Эта подпрограмма вызывается по адресу IRQL = PASSIVE_LEVEL.
Эта подпрограмма объявляется следующим образом:
typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
IN PFLT_PORT ClientPort,
IN PVOID ServerPortCookie,
IN PVOID ConnectionContext,
IN ULONG SizeOfContext,
OUT PVOID *ConnectionPortCookie
);
ClientPort
Непрозрачный дескриптор для нового порта клиента, установленного между приложением в пользовательском режиме и драйвером минифильтра в режиме ядра.
Драйвер минифильтра должен передать этот дескриптор в качестве параметра ClientPortв FltSendMessage при отправке сообщений на этом клиентском порту и ответе на их сообщения. (Обратите внимание, что это не то же самое, что дескриптор ServerPort , возвращенный FltCreateCommunicationPort.)
Драйвер минифильтра должен в конечном итоге закрыть этот клиентский порт. Порт клиента закрывается путем вызова FltCloseClientPort, обычно из подпрограммы DisconnectNotifyCallback драйвера минифильтра.
ServerPortCookie
Указатель на контекстные сведения, определенные драйвером минифильтра. Эти сведения можно использовать для различения нескольких портов сервера связи, созданных одним и тем же драйвером минифильтра. При создании порта сервера драйвер минифильтра передал этот указатель контекста в качестве параметра в FltCreateCommunicationPort.
ConnectionContext
Указатель контекстной информации, который приложение пользовательского режима передало в параметре lpContextв FilterConnectCommunicationPort.
SizeOfContext
Размер (в байтах) буфера, на который указывает ConnectionContext .
ConnectionPortCookie
Указатель на сведения, которые однозначно идентифицируют этот порт клиента. Эти сведения определяются драйвером минифильтра. Диспетчер фильтров передает этот указатель контекста в качестве параметра в подпрограммы DisconnectNotifyCallback и MessageNotifyCallback драйвера минифильтра.
[in] DisconnectNotifyCallback
Указатель на подпрограмму обратного вызова, предоставляемую вызывающей стороны, которая вызывается всякий раз, когда число дескрипторов пользовательского режима для порта клиента достигает нуля или когда драйвер минифильтра будет выгружен. Этот параметр является обязательным и не может иметь значение NULL. Эта подпрограмма вызывается по адресу IRQL = PASSIVE_LEVEL.
Эта подпрограмма объявляется следующим образом:
typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
IN PVOID ConnectionCookie
);
ConnectionCookie
Указатель на сведения, которые однозначно идентифицируют этот порт клиента. Эти сведения определяются драйвером минифильтра. При создании порта клиента драйвер минифильтра вернул этот указатель контекста в параметре ConnectionPortCookie своей подпрограммы ConnectNotifyCallback .
[in, optional] MessageNotifyCallback
Указатель на подпрограмму обратного вызова, предоставляемую вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму в irQL = PASSIVE_LEVEL всякий раз, когда приложение пользовательского режима вызывает FilterSendMessage для отправки сообщения драйверу минифильтра через клиентский порт. Этот параметр является необязательным и может иметь значение NULL. Если он имеет значение NULL, любой запрос, сделанный из пользовательского режима для отправки данных на порт, будет получать ошибку.
Эта подпрограмма объявляется следующим образом:
typedef NTSTATUS
(*PFLT_MESSAGE_NOTIFY) (
IN PVOID PortCookie,
IN PVOID InputBuffer OPTIONAL,
IN ULONG InputBufferLength,
OUT PVOID OutputBuffer OPTIONAL,
IN ULONG OutputBufferLength,
OUT PULONG ReturnOutputBufferLength
);
PortCookie
Указатель на сведения, которые однозначно идентифицируют этот порт клиента. Эти сведения определяются драйвером минифильтра. При создании порта клиента драйвер минифильтра вернул этот указатель контекста в параметре ConnectionPortCookie своей подпрограммы ConnectNotifyCallback .
InputBuffer
Указатель на буфер, выделенный вызывающим объектом, содержащий сообщение, которое будет отправлено драйверу минифильтра.
Обратите внимание, что InputBuffer — это указатель на необработанный, разблокированный буфер пользовательского режима. Этот указатель действителен только в контексте процесса пользовательского режима и должен быть доступен только из блока try/except .
Диспетчер фильтров вызывает ProbeForRead для проверки этого указателя, но не гарантирует правильность выравнивания буфера. Если буфер содержит структуры, имеющие требования к выравниванию, драйвер минифильтра отвечает за выполнение всех необходимых проверок выравнивания. Для этого драйвер минифильтра может использовать макрос IS_ALIGNED , как показано в примере драйвера минифильтра MiniSpy.
Этот параметр является необязательным и может иметь значение NULL.
InputBufferLength
Размер (в байтах) буфера, на который указывает InputBuffer . Этот параметр игнорируется, если InputBuffer имеет значение NULL.
OutputBuffer
Указатель на буфер, выделенный вызывающим объектом, который получает ответ (при наличии) от драйвера минифильтра.
Обратите внимание, что OutputBuffer — это указатель на необработанный, разблокированный буфер пользовательского режима. Этот указатель действителен только в контексте процесса пользовательского режима и должен быть доступен только из блока try/except .
Диспетчер фильтров вызывает ProbeForWrite для проверки этого указателя, но не гарантирует правильность выравнивания буфера. Если буфер содержит структуры, имеющие требования к выравниванию, драйвер минифильтра отвечает за выполнение всех необходимых проверок выравнивания. Для этого драйвер минифильтра может использовать макрос IS_ALIGNED , как показано в примере драйвера минифильтра MiniSpy.
Этот параметр является необязательным и может иметь значение NULL.
OutputBufferLength
Размер (в байтах) буфера, на который указывает OutputBuffer . Этот параметр игнорируется, если OutputBuffer имеет значение NULL.
ReturnOutputBufferLength
Указатель на переменную, выделенную вызывающим объектом, которая получает количество байтов, возвращаемых в буфере, на который указывает OutputBuffer .
[in] MaxConnections
Максимальное количество одновременных клиентских подключений для этого порта сервера. Этот параметр является обязательным и должен быть больше нуля.
Возвращаемое значение
Функция FltCreateCommunicationPort возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:
Код возврата | Описание |
---|---|
|
Указанный фильтр будет снесен. Это код ошибки. |
|
FltCreateCommunicationPort столкнулся с ошибкой выделения пула. Это код ошибки. |
|
Порт связи драйвера минифильтра с тем же именем уже существует. Имена портов должны быть уникальными. Это код ошибки. |
Комментарии
Драйвер минифильтра вызывает FltCreateCommunicationPort для создания объекта порта сервера связи.
После создания порта сервера приложение пользовательского режима может подключиться к порту, вызвав FilterConnectCommunicationPort. При подключении приложение пользовательского режима может отправлять и получать сообщения, вызывая функции обмена сообщениями в пользовательском режиме, такие как FilterSendMessage, FilterGetMessage и FilterReplyMessage.
Вызывающие объекты должны установить флаг атрибутов OBJ_KERNEL_HANDLE для параметра ObjectAttributesобъекта FltCreateCommunicationPort. Установка этого флага предотвращает использование дескриптора порта сервера связи драйвера минифильтра процессом пользовательского режима, в контексте которого может быть запущен вызывающий объект FltCreateCommunicationPort . Если этот флаг не установлен, Функция FltCreateCommunicationPort возвращает STATUS_INVALID_PARAMETER.
Любой порт сервера, созданный командой FltCreateCommunicationPort , в конечном итоге должен быть закрыт путем вызова Метода FltCloseCommunicationPort. При закрытии порта сервера новые подключения к порту сервера не допускаются, и все вызовы FilterConnectCommunicationPort завершаются ошибкой . Однако все существующие подключения остаются открытыми до тех пор, пока они не будут закрыты приложением пользовательского режима или драйвером минифильтра или пока драйвер минифильтра не будет выгружен.
Требования
Требование | Значение |
---|---|
Целевая платформа | Универсальное |
Верхняя часть | fltkernel.h (включая Fltkernel.h) |
Библиотека | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | PASSIVE_LEVEL |
См. также раздел
FilterConnectCommunicationPort
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по