FILTER_PAUSE fonction de rappel (ndis.h)

Article
02/26/2024

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

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

Syntaxe

FILTER_PAUSE FilterPause;

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

Paramètres

[in] FilterModuleContext

Handle de la zone de contexte pour le 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 retournée

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

Code de retour	Description
NDIS_STATUS_SUCCESS	FilterPause a correctement suspendu le module de filtre spécifié.
NDIS_STATUS_PENDING	Le pilote de filtre termine la requête de manière asynchrone avec un appel à la fonction NdisFPauseComplete .

Remarques

FilterPause est une fonction obligatoire. NDIS peut appeler FilterPause lorsque le module de filtre est à l’état En cours d’exécution . Le module de filtre passe à 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 Fonction NdisFSendNetBufferListsComplete pour toutes les mémoires tampons d’envoi en file d’attente créées par un pilote overlying.
Doit appeler le Fonction NdisFReturnNetBufferLists pour toutes les mémoires tampons de réception en file d’attente créées par un pilote sous-jacent.
Doit attendre que NDIS retourne toutes les demandes d’envoi en attente dont le pilote est originaire Fonction FilterSendNetBufferListsComplete .
Doit attendre que le NDIS retourne toutes les indications de réception en suspens indiquant que le conducteur est originaire du Fonction FilterReturnNetBufferLists .

Une fois que le pilote de filtre a retourné NDIS_STATUS_SUCCESS à partir de FilterPause ou appelé la fonction NdisFPauseComplete , l’opération de pause est terminée. Le module de filtre est à l’état Suspendu .

Dans les états Suspendu ou Suspendu, un pilote de filtre doit continuer à gérer les requêtes OID ou les indications status. Le pilote doit rejeter les appels à son Fonction FilterSendNetBufferLists . Le pilote peut passer des appels à son Fonction FilterReceiveNetBufferLists . Toutefois, le pilote ne peut pas passer les mémoires tampons qu’il a créées. Le conducteur ne doit pas être à l’origine d’aucune indication 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 ni recevoir d’indications.

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

NDIS appelle FilterPause à IRQL = PASSIVE_LEVEL.

Exemples

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 fonction permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de 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 lors de l’exécution des 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 Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	PASSIVE_LEVEL