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	指向包含端口对象的唯一名称（例如 L“\MyFilterPort”）的 UNICODE_STRING 结构的指针。
SecurityDescriptor	指向要应用于端口对象的安全描述符（SECURITY_DESCRIPTOR）的指针。如果需要，可以通过调用 FltBuildDefaultSecurityDescriptor来创建默认的安全描述符。
属性	指定端口句柄所需属性的标志的位掩码。这些标志必须包括OBJ_KERNEL_HANDLE。调用方还可以选择设置OBJ_CASE_INSENSITIVE标志，该标志指示名称查找代码应忽略 ObjectName 而不是执行完全匹配搜索的情况。

ServerPortCookie

[in，可选]指向微筛选器定义的上下文信息的指针。此信息可用于区分由同一微型筛选器创建的多个通信服务器端口。 FltMgr 将此上下文指针作为参数传递给 ConnectNotifyCallback 例程。此参数是可选的，可以是 NULL。

ConnectNotifyCallback

[in]指向调用方提供的 ConnectNotifyCallback 回调例程的指针。每当用户模式应用程序调用 filterConnectCommunicationPort 以向微型筛选器发送连接请求时，FltMgr 调用此例程。此参数是必需的，不能为 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）来发送和接收消息。

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

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

有关详细信息，请参阅用户模式与微型筛选器之间的通信。