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	指定的 Filter 正在被拆毀。這是錯誤碼。
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 的呼叫都會失敗。不過，任何現有的連線都會保持開啟狀態，直到使用者模式應用程式或迷你篩選程式關閉，或卸除迷你篩選為止。

如需詳細資訊，請參閱使用者模式與迷你篩選之間的通訊。