FltCreateCommunicationPort-Funktion (fltkernel.h)

Artikel
07/16/2024

FltCreateCommunicationPort erstellt einen Kommunikationsserverport, auf dem ein Minifilter Verbindungsanforderungen von Anwendungen und Diensten im Benutzermodus empfangen kann.

Syntax

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
);

Parameter

Filter

[in] Undurchsichtiger Filterzeiger für den Aufrufer.

ServerPort

[out] Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein undurchsichtiges Porthandle für den Kommunikationsserverport empfängt. Der Minifilter verwendet dieses Handle, um eingehende Verbindungsanforderungen aus einer Benutzermodusanwendung zu überwachen.

ObjectAttributes

[in] Zeigen Sie auf eine OBJECT_ATTRIBUTES-Struktur, die die Attribute des Kommunikationsserverports angibt. Diese Struktur muss durch einen vorherigen Aufruf von InitializeObjectAttributesinitialisiert worden sein. Dieser Parameter ist erforderlich und kann nicht NULL sein. Elemente dieser Struktur für ein Kommunikationsportobjekt umfassen Folgendes.

Mitglied	Wert
Länge	InitializeObjectAttributes legt dieses Element auf `sizeof(OBJECT_ATTRIBUTES)`fest.
ObjectName-	Zeiger auf eine UNICODE_STRING Struktur, die einen eindeutigen Namen (z. B. L"\MyFilterPort") für das Portobjekt enthält.
SecurityDescriptor-	Zeiger auf einen Sicherheitsdeskriptor (SECURITY_DESCRIPTOR), der auf das Portobjekt angewendet werden soll. Bei Bedarf kann ein Standardsicherheitsdeskriptor erstellt werden, indem FltBuildDefaultSecurityDescriptoraufgerufen wird.
Attribute	Bitmaske von Flags, die die gewünschten Attribute für den Porthandle angeben. Diese Flags müssen OBJ_KERNEL_HANDLE enthalten. Der Aufrufer kann optional auch das OBJ_CASE_INSENSITIVE Flag festlegen, das angibt, dass der Name-Nachschlagecode die Groß-/Kleinschreibung ObjectName- ignorieren soll, anstatt eine Suche mit exakter Übereinstimmung durchzuführen.

ServerPortCookie

[in, optional] Zeiger auf Kontextinformationen, die vom Minifilter definiert werden. Diese Informationen können verwendet werden, um zwischen mehreren Kommunikationsserverports zu unterscheiden, die vom gleichen Minifilter erstellt werden. FltMgr diesen Kontextzeiger als Parameter an die ConnectNotifyCallback Routine übergibt. Dieser Parameter ist optional und kann NULL sein.

ConnectNotifyCallback

[in] Zeiger auf eine vom Aufrufer bereitgestellte ConnectNotifyCallback Rückrufroutine. FltMgr diese Routine aufruft, wenn eine Anwendung im Benutzermodus FilterConnectCommunicationPort aufruft, um eine Verbindungsanforderung an den Minifilter zu senden. Dieser Parameter ist erforderlich und kann nicht NULL sein.

DisconnectNotifyCallback

[in] Zeiger auf eine vom Aufrufer bereitgestellte DisconnectNotifyCallback Rückrufroutine. FltMgr diese Routine aufruft, wenn die Anzahl der Benutzermodushandle für den Clientport null erreicht oder der Minifilter gerade entladen werden soll. Dieser Parameter ist erforderlich und kann nicht NULL sein.

MessageNotifyCallback

[in, optional] Zeiger auf eine vom Aufrufer bereitgestellte MessageNotifyCallback Rückrufroutine. FltMgr diese Routine aufruft, wenn eine Anwendung im Benutzermodus FilterSendMessage aufruft, um eine Nachricht über den Clientport an den Minifilter zu senden. Dieser Parameter ist optional und kann NULL sein. Wenn es NULL ist, erhält jede Anforderung vom Benutzermodus, Daten an den Port zu senden, einen Fehler.

MaxConnections

[in] Maximale Anzahl gleichzeitiger Clientverbindungen, die für diesen Serverport zulässig sind. Dieser Parameter ist erforderlich und muss größer als Null sein.

Rückgabewert

FltCreateCommunicationPort gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert wie einen der folgenden zurück.

Rückgabecode	Beschreibung
STATUS_FLT_DELETING_OBJECT	Der angegebene Filter- wird heruntergerissen. Dies ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort ein Poolzuordnungsfehler aufgetreten ist. Dies ist ein Fehlercode.
STATUS_OBJECT_NAME_COLLISION	Ein Minifilterkommunikationsport mit demselben Namen ist bereits vorhanden. Portnamen müssen eindeutig sein. Dies ist ein Fehlercode.

Bemerkungen

Ein Minifilter ruft FltCreateCommunicationPort- auf, um ein Kommunikationsserverportobjekt zu erstellen.

Nachdem der Serverport erstellt wurde, kann eine Benutzermodusanwendung eine Verbindung mit dem Port herstellen, indem FilterConnectCommunicationPortaufgerufen wird. Wenn eine Verbindung hergestellt wird, kann die Benutzermodusanwendung Nachrichten senden und empfangen, indem Nachrichten im Benutzermodus aufgerufen werden, z. B. FilterSendMessage-, FilterGetMessage-und FilterReplyMessage.

Aufrufer müssen das attribut OBJ_KERNEL_HANDLE Attributes für den ObjectAttributes Parameter von FltCreateCommunicationPortfestlegen. Durch Festlegen dieses Flags wird verhindert, dass der Minifilter-Kommunikationsserver-Porthandle von einem Benutzermodusprozess verwendet wird, in dessen Kontext ein Aufrufer von FltCreateCommunicationPort ausgeführt wird. Wenn dieses Flag nicht festgelegt ist, gibt FltCreateCommunicationPort STATUS_INVALID_PARAMETER zurück.

Jeder Serverport, der FltCreateCommunicationPort erstellt, muss schließlich durch Aufrufen FltCloseCommunicationPortgeschlossen werden. Wenn der Serverport geschlossen ist, sind keine neuen Verbindungen mit dem Serverport zulässig, und alle Aufrufe an FilterConnectCommunicationPort fehlschlagen. Alle vorhandenen Verbindungen bleiben jedoch geöffnet, bis sie von der Benutzermodusanwendung oder dem Minifilter geschlossen werden, oder bis der Minifilter entladen wird.

Weitere Informationen finden Sie unter Kommunikation zwischen Benutzermodus und Minifiltern.