Fonction FltCreateCommunicationPort (fltkernel.h)

Article
08/07/2023

FltCreateCommunicationPort crée un port de serveur de communication sur lequel un pilote de minifiltre peut recevoir des demandes de connexion d’applications en mode utilisateur.

Syntaxe

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

Paramètres

[in] Filter

Pointeur de filtre opaque pour l’appelant.

[out] ServerPort

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

[in] ObjectAttributes

Pointeur vers une structure de 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 avoir la valeur NULL. Les membres de cette structure pour un objet de port de communication incluent les éléments suivants.

Membre	Valeur
Longueur ULONG	InitializeObjectAttributes définit ce membre sur sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Pointeur vers une structure UNICODE_STRING contenant un nom unique (par exemple, L"\\MyFilterPort ») pour l’objet port.
PSECURITY_DESCRIPTOR 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.
AttributsULONG	Masque de bits d’indicateurs spécifiant les attributs souhaités pour le handle de port. Ces indicateurs doivent inclure OBJ_KERNEL_HANDLE. L’appelant peut également éventuellement définir l’indicateur OBJ_CASE_INSENSITIVE, ce qui indique que le code de recherche de nom doit ignorer la casse de ObjectName plutôt que d’effectuer une recherche de correspondance exacte.

[in, optional] ServerPortCookie

Pointeur vers les informations de contexte définies par le pilote de minifiltre. Ces informations peuvent être utilisées pour faire la distinction entre plusieurs ports de serveur de communication créés par le même pilote de minifiltre. Le Gestionnaire de filtres transmet ce pointeur de contexte en tant que paramètre à la routine ConnectNotifyCallback . Ce paramètre est facultatif et peut être NULL.

[in] ConnectNotifyCallback

Pointeur vers une routine de rappel fournie par l’appelant. Le Gestionnaire de filtres appelle cette routine chaque fois qu’une application en mode utilisateur appelle FilterConnectCommunicationPort pour envoyer une demande de connexion au pilote de minifiltre. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL. Cette routine est appelée dans IRQL = PASSIVE_LEVEL.

Cette routine est déclarée comme suit :

typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
      IN PFLT_PORT ClientPort,
      IN PVOID ServerPortCookie,
      IN PVOID ConnectionContext,
      IN ULONG SizeOfContext,
      OUT PVOID *ConnectionPortCookie
      );

ClientPort

Handle opaque pour le nouveau port client qui est établi entre l’application en mode utilisateur et le pilote de minifiltre en mode noyau.

Le pilote de minifiltre doit passer ce handle en tant que paramètre ClientPort à FltSendMessage lors de l’envoi et de la réponse aux messages sur ce port client. (Notez que ce n’est pas la même chose que le handle ServerPort retourné par FltCreateCommunicationPort.)

Le pilote de minifiltre doit éventuellement fermer ce port client. Le port client est fermé en appelant FltCloseClientPort, généralement à partir de la routine DisconnectNotifyCallback du pilote minifiltre.

ServerPortCookie

Pointeur vers les informations de contexte définies par le pilote de minifiltre. Ces informations peuvent être utilisées pour faire la distinction entre plusieurs ports de serveur de communication créés par le même pilote de minifiltre. Lorsque le port du serveur a été créé, le pilote de minifiltre a transmis ce pointeur de contexte en tant que paramètre à FltCreateCommunicationPort.

ConnectionContext

Pointeur d’informations de contexte que l’application en mode utilisateur a passé le paramètre lpContext à FilterConnectCommunicationPort.

SizeOfContext

Taille, en octets, de la mémoire tampon vers laquelle pointe ConnectionContext .

ConnectionPortCookie

Pointeur vers les informations qui identifient de manière unique ce port client. Ces informations sont définies par le pilote de minifiltre. Le Gestionnaire de filtres transmet ce pointeur de contexte en tant que paramètre aux routines DisconnectNotifyCallback et MessageNotifyCallback du pilote minifilter.

[in] DisconnectNotifyCallback

Pointeur vers une routine de rappel fournie par l’appelant à appeler chaque fois que le nombre de handles en mode utilisateur pour le port client atteint zéro ou lorsque le pilote de minifiltre est sur le point d’être déchargé. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL. Cette routine est appelée dans IRQL = PASSIVE_LEVEL.

Cette routine est déclarée comme suit :

typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
      IN PVOID ConnectionCookie
      );

ConnectionCookie

Pointeur vers les informations qui identifient de manière unique ce port client. Ces informations sont définies par le pilote de minifiltre. Lorsque le port client a été créé, le pilote de minifiltre a renvoyé ce pointeur de contexte dans le paramètre ConnectionPortCookie de sa routine ConnectNotifyCallback .

[in, optional] MessageNotifyCallback

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

Cette routine est déclarée comme suit :

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

Pointeur vers une mémoire tampon allouée à l’appelant contenant le message à envoyer au pilote de minifiltre.

Notez que InputBuffer est un pointeur vers une mémoire tampon brute en mode utilisateur déverrouillée. Ce pointeur est valide uniquement dans le contexte du processus en mode utilisateur et ne doit être accessible qu’à partir d’un bloc try/excepté .

Le gestionnaire de filtres appelle ProbeForRead pour valider ce pointeur, mais il ne garantit pas que la mémoire tampon est correctement alignée. Si la mémoire tampon contient des structures qui ont des exigences d’alignement, le pilote de minifiltre est chargé d’effectuer toutes les vérifications d’alignement nécessaires. Pour ce faire, le pilote de minifiltre peut utiliser la macro IS_ALIGNED , comme indiqué dans l’exemple de pilote minifiltre MiniSpy.

Ce paramètre est facultatif et peut être NULL.

InputBufferLength

Taille, en octets, de la mémoire tampon vers laquelle InputBuffer pointe. Ce paramètre est ignoré si InputBuffer a la valeur NULL.

OutputBuffer

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit la réponse (le cas échéant) du pilote de minifiltre.

Notez que OutputBuffer est un pointeur vers une mémoire tampon brute en mode utilisateur déverrouillée. Ce pointeur est valide uniquement dans le contexte du processus en mode utilisateur et ne doit être accessible qu’à partir d’un bloc try/excepté .

Le gestionnaire de filtres appelle ProbeForWrite pour valider ce pointeur, mais il ne garantit pas que la mémoire tampon est correctement alignée. Si la mémoire tampon contient des structures qui ont des exigences d’alignement, le pilote de minifiltre est chargé d’effectuer toutes les vérifications d’alignement nécessaires. Pour ce faire, le pilote de minifiltre peut utiliser la macro IS_ALIGNED , comme indiqué dans l’exemple de pilote minifiltre MiniSpy.

Ce paramètre est facultatif et peut être NULL.

OutputBufferLength

Taille, en octets, de la mémoire tampon vers laquelle pointe OutputBuffer . Ce paramètre est ignoré si OutputBuffer a la valeur NULL.

ReturnOutputBufferLength

Pointeur vers une variable allouée par l’appelant qui reçoit le nombre d’octets retournés dans la mémoire tampon vers laquelle pointe OutputBuffer .

[in] MaxConnections

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 retournée

FltCreateCommunicationPort retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_FLT_DELETING_OBJECT	Le filtre spécifié est en cours de démonté. 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 de pilote minifiltre 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 pilote de minifiltre 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. Lorsqu’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, FilterGetMessage et 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 le handle de port du serveur de communication du pilote minifilter d’être utilisé 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 créé par FltCreateCommunicationPort doit ê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 pilote de minifiltre, ou jusqu’à ce que le pilote de minifiltre soit déchargé.