FltCreateCommunicationPort 函式 (fltkernel.h)

發行項
02/29/2024

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”) 。
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

使用者模式應用程式傳遞至 FilterConnectCommunicationPort 之 lpContext 參數的內容資訊指標。

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 是原始、解除鎖定使用者模式緩衝區的指標。此指標只在使用者模式進程的內容中有效，而且只能從 try/ 中存取，但區塊除外。

篩選管理員會呼叫 ProbeForRead 來驗證此指標，但無法確保緩衝區正確對齊。如果緩衝區包含具有對齊需求的結構，迷你篩選驅動程式會負責執行任何必要的對齊檢查。若要這樣做，迷你篩選驅動程式可以使用 IS_ALIGNED 宏，如 MiniSpy 範例迷你篩選驅動程式所示。

此參數是選擇性的，可以是 NULL。

InputBufferLength

InputBuffer 指向的緩衝區大小，以位元組為單位。如果 InputBuffer 為 NULL，則會忽略此參數。

OutputBuffer

呼叫端配置的緩衝區指標，如果來自迷你篩選驅動程式的任何) ，則會接收回復 (。

請注意， OutputBuffer 是原始、解除鎖定使用者模式緩衝區的指標。此指標只在使用者模式進程的內容中有效，而且只能從 try/ 中存取，但區塊除外。

篩選管理員會呼叫 ProbeForWrite 來驗證此指標，但無法確保緩衝區正確對齊。如果緩衝區包含具有對齊需求的結構，迷你篩選驅動程式會負責執行任何必要的對齊檢查。若要這樣做，迷你篩選驅動程式可以使用 IS_ALIGNED 宏，如 MiniSpy 範例迷你篩選驅動程式所示。

此參數是選擇性的，可以是 NULL。

OutputBufferLength

OutputBuffer 指向的緩衝區大小，以位元組為單位。如果 OutputBuffer 為 NULL，則會忽略此參數。

ReturnOutputBufferLength

呼叫端配置的變數指標，該變數會接收 OutputBuffer 指向之緩衝區中傳回的位元組數目。

[in] MaxConnections

此伺服器埠允許的同時客戶端連線數目上限。這個參數是必要的，而且必須大於零。

傳回值

FltCreateCommunicationPort 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一項：

傳回碼	Description
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 的呼叫都會失敗。不過，任何現有的連線都會保持開啟狀態，直到使用者模式應用程式或迷你篩選驅動程式關閉，或直到卸除迷你篩選驅動程序為止。