FILTER_RESTART fonction de rappel (ndis.h)

Article
08/07/2023

La fonction FilterRestart lance une opération de redémarrage pour le module de filtre spécifié.

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

Syntaxe

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Paramètres

[in] FilterModuleContext

Handle de la zone de contexte pour le module de filtre que le pilote de filtre doit redémarrer. Le pilote de filtre a créé et initialisé cette zone de contexte dans la fonction FilterAttach .

[in] RestartParameters

Pointeur vers un NDIS_FILTER_RESTART_PARAMETERS structure qui définit les paramètres de redémarrage du module de filtre.

Valeur retournée

FilterRestart retourne l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	FilterRestart a correctement redémarré 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 NdisFRestartComplete une fois l’opération de redémarrage terminée.
NDIS_STATUS_RESOURCES	FilterRestart a échoué en raison de ressources insuffisantes.
NDIS_STATUS_FAILURE	Aucune des valeurs status précédentes ne s’applique. Le pilote de filtre doit appeler la fonction NdisWriteEventLogEntry avec des paramètres qui spécifient la raison de l’échec.

Remarques

FilterRestart est une fonction obligatoire pour les pilotes de filtre. NDIS peut appeler FilterRestart lorsqu’un module de filtre est à l’état Suspendu . Le module de filtre passe à l’état Redémarrage au début de l’exécution de FilterRestart.

Lorsque NDIS appelle FilterRestart, un pilote de filtre :

Doit effectuer les opérations requises pour redémarrer les opérations d’envoi et de réception normales.
Lit ou écrit éventuellement des paramètres de configuration.
Réalloue éventuellement les pools de mémoires tampons.
Modifie éventuellement les attributs de redémarrage spécifiés dans le membre RestartAttributes du NDIS_FILTER_RESTART_PARAMETERS structure. Si le pointeur dans RestartAttributes a la valeur NULL, le pilote de filtre ne doit pas modifier ou ajouter à la liste des attributs de redémarrage. Si le pointeur dans RestartAttributes n’est pas NULL, il pointe vers la première structure NDIS_RESTART_ATTRIBUTES dans la liste des attributs de redémarrage. Si un pilote de filtre ne redémarre pas, il ne doit pas modifier d’attributs.
Utilise éventuellement des requêtes OID pour interroger ou définir des informations dans les pilotes sous-jacents. Les pilotes de filtre ne doivent pas émettre de demandes d’OID pour des informations déjà fournies dans la liste des attributs de redémarrage.
Retourne NDIS_STATUS_SUCCESS ou un status d’échec.

Si un pilote de filtre modifie la liste des attributs de redémarrage, le pilote de filtre :

Ne doit pas modifier d’attributs spécifiques au média s’il ne reconnaît pas l’OID dans le membre Oid du NDIS_RESTART_ATTRIBUTES structure.
Peut ajouter de nouveaux attributs spécifiques au média à la liste des attributs de redémarrage. Dans ce cas, le pilote de filtre doit allouer une nouvelle structure NDIS_RESTART_ATTRIBUTES, par exemple, avec le Fonction NdisAllocateMemoryWithTagPriority et fournir de l’espace mémoire pour les nouveaux attributs. Après avoir propagé les attributs de redémarrage à des pilotes sur-mentants, NDIS libère la mémoire des attributs pour les pilotes de filtre.
Peut modifier les attributs spécifiques au média dans la liste des attributs de redémarrage. Si le pilote de filtre nécessite plus d’espace mémoire, il peut libérer la structure NDIS_RESTART_ATTRIBUTES avec la fonction NdisFreeMemory et allouer une nouvelle structure pour contenir les informations modifiées. Après avoir propagé les attributs de redémarrage à des pilotes sur-mentants, NDIS libère la mémoire des attributs pour les pilotes de filtre.
Doit, si le membre Oid dans la structure NDIS_RESTART_ATTRIBUTES est OID_GEN_MINIPORT_RESTART_ATTRIBUTES, assurez-vous que le NDIS_RESTART_GENERAL_ATTRIBUTES structure contient les informations requises par le pilote de filtre. Pour vous assurer que la structure NDIS_RESTART_GENERAL_ATTRIBUTES contient les informations requises, vous devez case activée le membre Revision dans la structure NDIS_OBJECT_HEADER qui est spécifiée dans le membre Header de la structure NDIS_RESTART_GENERAL_ATTRIBUTES.
Note Un pilote de filtre peut modifier n’importe quel membre de la structure NDIS_RESTART_GENERAL_ATTRIBUTES. Si certains attributs que le pilote de filtre doit modifier ne sont pas inclus dans la révision de la structure fournie par NDIS, le pilote de filtre doit s’appuyer sur des pilotes trop étendus pour émettre des demandes d’OID pour les attributs manquants. Le pilote de filtre peut modifier les attributs lorsqu’il termine la requête OID.
Doit, si le pilote de filtre change les attributs de redémarrage, fournir une fonction FilterOidRequest . Le pilote de filtre doit s’assurer que les informations que les pilotes sur-ment reçoivent dans les attributs de redémarrage sont cohérentes avec les informations qu’ils reçoivent en réponse aux demandes OID.

Une fois que le pilote de filtre a retourné son status ou appelé la fonction NdisFRestartComplete, l’opération de redémarrage est terminée. Si l’opération s’est terminée correctement, le module de filtre est à l’état En cours d’exécution et le traitement normal de l’envoi et de la réception reprend. Si l’opération de redémarrage a échoué, le module de filtre revient à l’état Suspendu .

NDIS appelle FilterRestart à IRQL = PASSIVE_LEVEL.

Exemples

Pour définir une fonction FilterRestart , 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 FilterRestart nommée « MyRestart », utilisez le type FILTER_RESTART comme indiqué dans cet exemple de code :

FILTER_RESTART MyRestart;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

Le type de fonction FILTER_RESTART 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_RESTART 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