FltCreateCommunicationPort, fonction (fltkernel.h)

Article
02/06/2025

FltCreateCommunicationPort crée un port de serveur de communication sur lequel un minifilter peut recevoir des demandes de connexion à partir d’applications et de services en mode utilisateur.

Syntaxe

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

Paramètres

Filter

[in] Pointeur de filtre opaque pour l’appelant.

ServerPort

[out] Pointeur vers une variable allouée par l’appelant qui reçoit un handle de port opaque pour le port du serveur de communication. Le minifilter utilise ce handle pour écouter les demandes de connexion entrantes à partir d’une application en mode utilisateur.

ObjectAttributes

[in] Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie les attributs du port du serveur de communication. Cette structure doit avoir été initialisée par un appel précédent à InitializeObjectAttributes. Ce paramètre est obligatoire et ne peut pas être NULL. Les membres de cette structure pour un objet de port de communication incluent les éléments suivants.

Membre	Valeur
longueur	InitializeObjectAttributes définit ce membre sur `sizeof(OBJECT_ATTRIBUTES)`.
ObjectName	Pointeur vers une structure UNICODE_STRING contenant un nom unique (par exemple, L"\MyFilterPort ») pour l’objet de port.
SecurityDescriptor	Pointeur vers un descripteur de sécurité (SECURITY_DESCRIPTOR) à appliquer à l’objet de port. Si nécessaire, un descripteur de sécurité par défaut peut être créé en appelant FltBuildDefaultSecurityDescriptor.
attributs	Masque de bits des indicateurs spécifiant les attributs souhaités pour le handle de port. Ces indicateurs doivent inclure OBJ_KERNEL_HANDLE. L’appelant peut également définir l’indicateur de OBJ_CASE_INSENSITIVE, ce qui indique que le code de recherche de noms doit ignorer le cas de ObjectName plutôt que d’effectuer une recherche exacte-correspondance.

ServerPortCookie

[in, facultatif] Pointeur vers les informations de contexte définies par le minifilter. Ces informations peuvent être utilisées pour distinguer plusieurs ports de serveur de communication créés par le même minifilter. fltMgr transmet ce pointeur de contexte en tant que paramètre à la routine ConnectNotifyCallback. Ce paramètre est facultatif et peut être NULL.

ConnectNotifyCallback

[in] Pointeur vers une routine de rappel fournie par l’appelant ConnectNotifyCallback. FltMgr appelle cette routine chaque fois qu’une application en mode utilisateur appelle FilterConnectCommunicationPort pour envoyer une demande de connexion au minifilter. Ce paramètre est obligatoire et ne peut pas être NULL.

DisconnectNotifyCallback

[in] Pointeur vers une routinede rappel fournie par l’appelantDisconnectNotifyCallback. FltMgr appelle cette routine chaque fois que le nombre de handles en mode utilisateur pour le port client atteint zéro ou lorsque le minifilter est sur le point d’être déchargé. Ce paramètre est obligatoire et ne peut pas être NULL.

MessageNotifyCallback

[in, facultatif] Pointeur vers une routine de rappel fournie par l’appelant MessageNotifyCallback. FltMgr appelle cette routine chaque fois qu’une application en mode utilisateur appelle FilterSendMessage pour envoyer un message au minifilter via le port client. Ce paramètre est facultatif et peut être NULL. S’il s’agit de NULL, toute demande effectuée à partir du mode utilisateur pour envoyer des données au port reçoit une erreur.

MaxConnections

[in] Nombre maximal de connexions clientes simultanées à autoriser pour ce port de serveur. Ce paramètre est obligatoire et doit être supérieur à zéro.

Valeur de retour

FltCreateCommunicationPort retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, telle que l’une des suivantes.

Retourner le code	Description
STATUS_FLT_DELETING_OBJECT	Le de filtre spécifié est en cours de déchirure. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_OBJECT_NAME_COLLISION	Un port de communication minifilter portant le même nom existe déjà. Les noms de port doivent être uniques. Il s’agit d’un code d’erreur.

Remarques

Un minifilter appelle FltCreateCommunicationPort pour créer un objet de port de serveur de communication.

Une fois le port du serveur créé, une application en mode utilisateur peut se connecter au port en appelant FilterConnectCommunicationPort. Quand elle est connectée, l’application en mode utilisateur peut envoyer et recevoir des messages en appelant des fonctions de messagerie en mode utilisateur telles que FilterSendMessage, FilterGetMessageet FilterReplyMessage.

Les appelants doivent définir l’indicateur Attributs OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributes de FltCreateCommunicationPort. La définition de cet indicateur empêche l’utilisation du handle de port du serveur de communication minifilter par un processus en mode utilisateur dans lequel un appelant de FltCreateCommunicationPort peut être en cours d’exécution. Si cet indicateur n’est pas défini, FltCreateCommunicationPort retourne STATUS_INVALID_PARAMETER.

Tout port de serveur qui FltCreateCommunicationPort crée doit finalement être fermé en appelant FltCloseCommunicationPort. Lorsque le port du serveur est fermé, aucune nouvelle connexion au port du serveur n’est autorisée, et tous les appels à FilterConnectCommunicationPort échouent. Toutefois, toutes les connexions existantes restent ouvertes jusqu’à ce qu’elles soient fermées par l’application en mode utilisateur ou le minifilter, ou jusqu’à ce que le minifilter soit déchargé.

Pour plus d’informations, consultez Communication entre le mode utilisateur et les mini-filtres.