FILTER_PAUSE fonction de rappel (ndis.h)

Article
02/07/2025

NDIS appelle la fonction FilterPause d’un pilote de filtre pour lancer une opération de pause pour le module de filtre spécifié.

Remarque Vous devez déclarer la fonction à l’aide du type FILTER_PAUSE. Pour plus d’informations, consultez la section Exemples suivants.

Syntaxe

FILTER_PAUSE FilterPause;

NDIS_STATUS FilterPause(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

Paramètres

[in] FilterModuleContext

Handle vers la zone de contexte du module de filtre que le pilote de filtre doit suspendre. Le pilote de filtre a créé et initialisé cette zone de contexte dans la fonction FilterAttach.

[in] PauseParameters

Pointeur vers un NDIS_FILTER_PAUSE_PARAMETERS structure qui définit les paramètres de pause pour le module de filtre.

Valeur de retour

Les pilotes NDIS ne peuvent pas échouer à une demande de pause. Le pilote de filtre doit appeler la fonction NdisWriteEventLogEntry avec les paramètres qui spécifient la raison des erreurs qui se produisent.

Retourner le code	Description
NDIS_STATUS_SUCCESS	FilterPause correctement suspendu le module de filtre spécifié.
NDIS_STATUS_PENDING	Le pilote de filtre termine la requête de façon asynchrone avec un appel à la fonction NdisFPauseComplete.

Remarques

FilterPause est une fonction requise. NDIS peut appeler FilterPause lorsque le module de filtre est dans l’état En cours d’exécution. Le module de filtre entre l’état de suspension au début de l’exécution dans la fonction FilterPause.

Un pilote de filtre effectue les opérations suivantes lorsque NDIS appelle FilterPause:

Doit appeler le NdisFSendNetBufferListsComplete fonction pour les mémoires tampons d’envoi en file d’attente créées par un pilote trop chargé.
Doit appeler le NdisFReturnNetBufferLists fonction pour toutes les mémoires tampons de réception mises en file d’attente créées par un pilote sous-jacent.
Doit attendre que NDIS retourne toutes les demandes d’envoi en attente que le pilote a générées au fonction FilterSendNetBufferListsComplete.
Doit attendre que le NDIS retourne toutes les indications de réception en attente que le pilote provient du fonction FilterReturnNetBufferLists.

Une fois que le pilote de filtre retourne NDIS_STATUS_SUCCESS de FilterPause ou appelle la fonction NdisFPauseComplete, l’opération de pause est terminée. Le module de filtre est dans l’état suspendu.

Dans le suspension ou états de suspendus, un pilote de filtre doit continuer à gérer les demandes OID ou les indications d’état. Le pilote doit rejeter les appels à son FilterSendNetBufferLists fonction. Le pilote peut passer des appels à son FilterReceiveNetBufferLists fonction. Toutefois, le pilote ne peut pas passer les mémoires tampons qu’il a créées. Le pilote ne doit pas provenir d’indications de réception ou d’envoi de demandes.

Dans l’état suspendu, le module de filtre ne doit pas générer de demandes d’envoi ou recevoir des indications.

NDIS appelle la fonction FilterRestart pour lancer une demande de redémarrage d’un module de filtre à l’état suspendu.

NDIS appelle FilterPause à IRQL = PASSIVE_LEVEL.

exemples de

Pour définir une fonction FilterPause, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions permet d'Analyse du code pour les pilotes, de vérificateur de pilotes statiques (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction FilterPause nommée « MyPause », utilisez le type FILTER_PAUSE comme indiqué dans cet exemple de code :

FILTER_PAUSE MyPause;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_PAUSE_PARAMETERS  FilterPauseParameters
    )
  {...}

Le type de fonction FILTER_PAUSE est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction FILTER_PAUSE dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Prise en charge dans NDIS 6.0 et versions ultérieures.
plateforme cible	Windows
d’en-tête	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL