FltCreateCommunicationPort 函数 (fltkernel.h)

项目
08/07/2023

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。通信端口对象的此结构的成员包括以下内容。

成员	Value
ULONG 长度	InitializeObjectAttributes 将此成员设置为 sizeof (OBJECT_ATTRIBUTES) 。
PUNICODE_STRING ObjectName	指向 UNICODE_STRING 结构的指针，该结构包含唯一名称 (例如端口对象的 L“\\MyFilterPort”) 。
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 。 (请注意，这与 FltCreateCommunicationPort.) 返回的 ServerPort 句柄不同

微筛选器驱动程序最终必须关闭此客户端端口。客户端端口通过调用 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

指向唯一标识此客户端端口的信息的指针。此信息由微筛选器驱动程序定义。创建客户端端口时，微筛选器驱动程序在其 ConnectNotifyCallback 例程的 ConnectionPortCookie 参数中返回此上下文指针。

[in, optional] MessageNotifyCallback

指向调用方提供的回调例程的指针。每当用户模式应用程序调用 FilterSendMessage 以通过客户端端口向微筛选器驱动程序发送消息时，筛选器管理器会在 IRQL = PASSIVE_LEVEL 调用此例程。此参数是可选的，可以为 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

InputBuffer

指向调用方分配的缓冲区的指针，该缓冲区包含要发送到微筛选器驱动程序的消息。

请注意， InputBuffer 是指向未锁定的原始用户模式缓冲区的指针。此指针仅在用户模式进程的上下文中有效，并且只能在尝试/（块除外）中访问。

筛选器管理器调用 ProbeForRead 来验证此指针，但它不确保缓冲区正确对齐。如果缓冲区包含具有对齐要求的结构，则微筛选器驱动程序负责执行任何必要的对齐检查。为此，微筛选器驱动程序可以使用 IS_ALIGNED 宏，如 MiniSpy 示例微筛选器驱动程序所示。

此参数是可选的，可以为 NULL。

InputBufferLength

InputBuffer 指向的缓冲区的大小（以字节为单位）。如果 InputBuffer 为 NULL，则忽略此参数。

OutputBuffer

指向调用方分配的缓冲区的指针，该缓冲区接收回复 (（如果任何) 来自微筛选器驱动程序）。

请注意， OutputBuffer 是指向未锁定的原始用户模式缓冲区的指针。此指针仅在用户模式进程的上下文中有效，并且只能在尝试/（块除外）中访问。

筛选器管理器调用 ProbeForWrite 来验证此指针，但它不确保缓冲区正确对齐。如果缓冲区包含具有对齐要求的结构，则微筛选器驱动程序负责执行任何必要的对齐检查。为此，微筛选器驱动程序可以使用 IS_ALIGNED 宏，如 MiniSpy 示例微筛选器驱动程序所示。

此参数是可选的，可以为 NULL。

OutputBufferLength

OutputBuffer 指向的缓冲区的大小（以字节为单位）。如果 OutputBuffer 为 NULL，则忽略此参数。

ReturnOutputBufferLength

指向调用方分配的变量的指针，该变量接收 OutputBuffer 指向的缓冲区中返回的字节数。

[in] MaxConnections

此服务器端口允许的最大同时客户端连接数。此参数是必需的，并且必须大于零。

返回值

FltCreateCommunicationPort 返回STATUS_SUCCESS或相应的 NTSTATUS 值，例如以下值之一：

返回代码	说明
STATUS_FLT_DELETING_OBJECT	指定的筛选器正在被拆除。这是错误代码。
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort 遇到池分配失败。这是错误代码。
STATUS_OBJECT_NAME_COLLISION	已存在同名的微筛选器驱动程序通信端口。端口名称必须是唯一的。这是错误代码。

注解

微筛选器驱动程序调用 FltCreateCommunicationPort 来创建通信服务器端口对象。

创建服务器端口后，用户模式应用程序可以通过调用 FilterConnectCommunicationPort 连接到该端口。连接后，用户模式应用程序可以通过调用 FilterSendMessage、FilterGetMessage 和 FilterReplyMessage 等用户模式消息传送函数来发送和接收消息。

调用方必须为 FltCreateCommunicationPort 的 ObjectAttributes 参数设置 OBJ_KERNEL_HANDLE Attributes 标志。设置此标志可防止用户模式进程使用微筛选器驱动程序通信服务器端口句柄，其上下文中可能正在运行 FltCreateCommunicationPort 的调用方。如果未设置此标志， FltCreateCommunicationPort 将返回STATUS_INVALID_PARAMETER。

由 FltCreateCommunicationPort 创建的任何服务器端口最终都必须通过调用 FltCloseCommunicationPort 关闭。服务器端口关闭后，不允许与服务器端口建立新的连接，并且对 FilterConnectCommunicationPort 的所有调用都失败。但是，任何现有连接将保持打开状态，直到用户模式应用程序或微筛选器驱动程序关闭，或者直到卸载微筛选器驱动程序。