FILTER_RESTART fonction de rappel (ndis.h)

Article
07/02/2025

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

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

Syntaxe

FILTER_RESTART FilterRestart;

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

Paramètres

[in] FilterModuleContext

Handle vers la zone de contexte du 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 de retour

FilterRestart retourne l’une des valeurs d’état suivantes :

Retourner le code	Description
NDIS_STATUS_SUCCESS	FilterRestart correctement redémarré 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 ndisFRestartComplete 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 d’état précédentes ne s’applique. Le pilote de filtre doit appeler la fonction NdisWriteEventLogEntry avec les paramètres qui spécifient la raison de l’échec.

Remarques

FilterRestart est une fonction requise pour les pilotes de filtre. NDIS peut appeler FilterRestart lorsqu’un module de filtre est dans l’état suspendu. Le module de filtre entre l’état redémarrage au début de l’exécution de FilterRestart.

Quand 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 des pools de mémoires tampons.
Modifie éventuellement les attributs de redémarrage spécifiés dans le membre RestartAttributes du structure NDIS_FILTER_RESTART_PARAMETERS. Si le pointeur dans RestartAttributes est NULL, le pilote de filtre ne doit pas modifier ou ajouter à la liste des attributs de redémarrage. Si le pointeur de RestartAttributes n’est pasNULL, 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.
Vous pouvez éventuellement utiliser 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 OID pour les informations déjà fournies dans la liste des attributs de redémarrage.
Retourne NDIS_STATUS_SUCCESS ou un état 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 aux médias s’il ne reconnaît pas l’OID dans le membre de l’OIDstructure NDIS_RESTART_ATTRIBUTES.
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 la NdisAllocateMemoryWithTagPriority fonction et fournissent de l’espace mémoire pour les nouveaux attributs. Après avoir propagé les attributs de redémarrage vers des pilotes trop chargés, 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 davantage 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 vers des pilotes trop chargés, 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 vérifier le membre révision dans la structure NDIS_OBJECT_HEADER spécifiée dans l’en-tête membre de la structure NDIS_RESTART_GENERAL_ATTRIBUTES.
Remarque 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 les pilotes surlysants pour émettre des demandes 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 modifie les attributs de redémarrage, fournissez une fonction FilterOidRequest. Le pilote de filtre doit s’assurer que les informations reçues par des pilotes trop grands 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 retourne son état ou appelle la fonction NdisFRestartComplete, l’opération de redémarrage est terminée. Si l’opération s’est terminée avec succès, le module de filtre se trouve dans le en cours d’exécution état et le traitement d’envoi et de réception normal est repris. Si l’opération de redémarrage a échoué, le module de filtre retourne à l’état suspendu.

NDIS appelle FilterRestart à IRQL = PASSIVE_LEVEL.

exemples de

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 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 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 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_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 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