Fonction FltSendMessage (fltkernel.h)

Article
08/07/2023

FltSendMessage envoie un message à une application en mode utilisateur en attente pour le compte d’un pilote minifilter ou d’un pilote minifilter instance.

Syntaxe

NTSTATUS FLTAPI FltSendMessage(
  [in]            PFLT_FILTER    Filter,
  [in]            PFLT_PORT      *ClientPort,
  [in]            PVOID          SenderBuffer,
  [in]            ULONG          SenderBufferLength,
  [out, optional] PVOID          ReplyBuffer,
  [in, out]       PULONG         ReplyLength,
  [in, optional]  PLARGE_INTEGER Timeout
);

Paramètres

[in] Filter

Pointeur de filtre opaque pour l’appelant. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] ClientPort

Pointeur vers une variable qui contient le pointeur de port client opaque pour le port de connexion entre l’application en mode utilisateur et le pilote minifilter en mode noyau. Pour plus d’informations sur le pointeur de port client, consultez la description du paramètre ConnectNotifyCallback dans l’entrée de référence pour FltCreateCommunicationPort.

[in] SenderBuffer

Pointeur vers une mémoire tampon allouée à l’appelant contenant le message à envoyer à l’application en mode utilisateur. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] SenderBufferLength

Taille, en octets, de la mémoire tampon vers laquelle pointe SenderBuffer . Pour plus d’informations , consultez Remarques .

[out, optional] ReplyBuffer

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit la réponse, le cas échéant, de l’application. Ce paramètre est facultatif et peut être NULL.

[in, out] ReplyLength

Taille, en octets, de la mémoire tampon vers laquelle ReplyBuffer pointe. Ce paramètre est facultatif, mais doit être non NULL lorsque ReplyBuffer n’a pas la valeur NULL.

[in, optional] Timeout

Pointeur vers une valeur de délai d’attente qui spécifie la durée totale absolue ou relative, en unités de 100 nanosecondes, pour laquelle l’appelant peut être placé dans un état d’attente jusqu’à ce que le message soit reçu par l’application en mode utilisateur et jusqu’à ce qu’il reçoive une réponse (le cas échéant).

Une valeur positive spécifie une heure absolue, par rapport au 1er janvier 1601. Une valeur négative spécifie un intervalle par rapport à l’heure actuelle. Définissez sur NULL si l’appelant peut être placé dans un état d’attente indéfiniment.

Valeur retournée

FltSendMessage retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, telle que l’une des valeurs suivantes :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	FltSendMessage a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_PORT_DISCONNECTED	Le port de communication a été déconnecté. Il s’agit d’un code d’erreur.
STATUS_THREAD_IS_TERMINATING	L’attente a été interrompue, car le thread a été arrêté par une application ou un utilisateur.
STATUS_TIMEOUT	L’intervalle de délai d’expiration a expiré avant la remise du message ou avant la réception d’une réponse. Il s’agit d’un code de réussite.

Remarques

FltSendMessage envoie un message à une application en mode utilisateur pour le compte d’un pilote minifilter ou d’un pilote minifilter instance.

Si l’application appelle FilterGetMessage pour obtenir le message avant que le pilote minifilter appelle FltSendMessage pour l’envoyer, le message est remis immédiatement. C’est généralement le cas lorsque l’application appelle FilterGetMessage à partir d’une boucle de message.

Sinon, si une application n’a pas appelé pour obtenir un message, le pilote minifilter est placé dans un état d’attente comme suit :

Si le délai d’expiration est différent de zéro et que l’application appelle FilterGetMessage avant l’expiration de l’intervalle de délai d’expiration, le message est remis.
Si le délai d’expiration est différent de zéro et que l’application n’appelle pas FilterGetMessage avant l’expiration de l’intervalle de délai d’expiration, le message n’est pas remis et FltSendMessage retourne STATUS_TIMEOUT. (Remarque : STATUS_TIMEOUT est un code de réussite.)
Si le délai d’expiration est égal à zéro, le pilote minifilter est placé dans un état d’attente indéfiniment. Lorsque l’application appelle FilterGetMessage, le message est remis.

Une fois le message remis, si ReplyBuffer a la valeur NULL, FltSendMessage retourne STATUS_SUCCESS.

Sinon, si ReplyBuffer n’a pas la valeur NULL, le pilote minifilter est placé dans un état d’attente comme suit :

Si le délai d’expiration est différent de zéro et que l’application appelle FilterReplyMessage avant l’expiration de l’intervalle de délai d’expiration, le pilote minifilter reçoit la réponse et FltSendMessage retourne STATUS_SUCCESS.
Si le délai d’expiration est différent de zéro et que le pilote minifilter ne reçoit pas de réponse avant l’expiration de l’intervalle de délai d’expiration, FltSendMessage retourne STATUS_TIMEOUT. (Remarque : STATUS_TIMEOUT est un code de réussite.)
Si le délai d’expiration est égal à zéro lorsque le pilote minifilter attend la réponse, le pilote minifilter est placé dans un état d’attente indéfiniment. Lorsque l’application appelle FilterReplyMessage, le pilote minifilter reçoit la réponse et FltSendMessage retourne STATUS_SUCCESS.

Notes

En raison des exigences de remplissage de structure (spécifiques au système), la précision est requise lorsque vous définissez la taille des mémoires tampons associées à FltSendMessage et FilterReplyMessage. Par exemple, supposons que les données doivent être envoyées via FilterReplyMessage à un minifiltre. Le composant en mode utilisateur peut déclarer la structure suivante pour ce faire :

typedef struct _REPLY_STRUCT
{
    FILTER_REPLY_HEADER Header;
    MY_STRUCT Data;  // The structure to be sent to the minifilter
} REPLY_STRUCT, *PREPLY_STRUCT;

Compte tenu de cette structure, il peut sembler évident que l’appelant de FilterReplyMessage affecterait à sizeof(REPLY_STRUCT)dwReplyBufferSize la valeur et définirait le paramètre ReplyLength de FltSendMessage sur la même valeur. Toutefois, en raison des idiosyncrasies de remplissage de structure, sizeof(REPLY_STRUCT) peut être supérieur à sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). Si tel est le cas, FltSendMessage retourne STATUS_BUFFER_OVERFLOW.

Par conséquent, il est recommandé d’appeler FilterReplyMessage et FltSendMessage (en tirant parti de l’exemple ci-dessus) en définissant dwReplyBufferSize et ReplyLength sur sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) au lieu de sizeof(REPLY_STRUCT). Cela garantit que tout remplissage supplémentaire à la fin de la structure REPLY_STRUCT est ignoré.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Correctif cumulatif Microsoft Windows 2000 1 pour les systèmes d’exploitation SP4, Windows XP SP2, Windows Server 2003 SP1 et ultérieur.
Plateforme cible	Universal
En-tête	fltkernel.h (incluez FltKernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL

Voir aussi

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort

Partager via