FILTER_ATTACH fonction de rappel (ndis.h)

Article
08/07/2023

NDIS appelle la fonction FilterAttach d’un pilote de filtre pour allouer et initialiser les structures de données d’un module de filtre.

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

Syntaxe

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Paramètres

[in] NdisFilterHandle

Handle NDIS qui identifie un module de filtre. Le pilote de filtre doit enregistrer ce handle. Le handle est requis dans les appels suivants aux fonctions NdisFXxx .

[in] FilterDriverContext

Handle que le pilote a passé au Fonction NdisFRegisterFilterDriver qui identifie la zone de contexte du pilote.

[in] AttachParameters

Pointeur vers un NDIS_FILTER_ATTACH_PARAMETERS structure qui définit les paramètres d’initialisation pour le module de filtre.

Valeur retournée

FilterAttach retourne l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	FilterAttach a correctement alloué et initialisé les structures de données pour ce module de filtre.
NDIS_STATUS_RESOURCES	Échec de FilterAttach en raison de ressources insuffisantes.
NDIS_STATUS_FAILURE	FilterAttach retourne NDIS_STATUS_FAILURE si aucune des valeurs 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

FilterAttach est une fonction obligatoire. NDIS appelle la fonction FilterAttach d’un pilote de filtre lorsque le module de filtre spécifié est à l’état Détaché . NDIS peut appeler FilterAttach à tout moment après le retour de l’appel à la fonction FilterSetOptions .

Au début de l’exécution dans FilterAttach, le module de filtre passe à l’état Attachement .

Les pilotes de filtre doivent éviter d’émettre des requêtes OID inutiles. Utilisez plutôt les informations dans NDIS_FILTER_ATTACH_PARAMETERS, le cas échéant, pour obtenir des informations sur les pilotes sous-jacents.

Un pilote de filtre effectue les opérations suivantes lorsque NDIS appelle FilterAttach.

Crée une zone de contexte pour le module de filtre et alloue des pools de mémoires tampons et d’autres ressources.
Appelle la fonction NdisFSetAttributes avec le NdisFilterHandle que NDIS a transmis à FilterAttach. Le paramètre FilterModuleContext de NdisFSetAttributes spécifie la zone de contexte du pilote de filtre pour ce module de filtre. NDIS transmet cette zone de contexte aux fonctions FilterXxx du pilote de filtre.
Lit éventuellement les paramètres de configuration à partir du Registre.
Si les opérations précédentes se sont terminées avec succès, le module de filtre passe à l’état Suspendu .
Si les opérations précédentes ont échoué, le pilote de filtre doit libérer toutes les ressources qu’il a allouées dans la fonction FilterAttach et retourner le module de filtre à l’état Détaché .
Retourne NDIS_STATUS_SUCCESS ou un code d’échec approprié.

Un pilote de filtre ne doit pas effectuer d’envoi de demandes, indiquer les données reçues, effectuer des requêtes OID ou faire status indications à partir de l’état d’attachement.

NDIS appelle la fonction FilterDetach d’un pilote de filtre pour libérer toutes les ressources associées à un module de filtre et retourner le module de filtre à l’état Détaché .

NDIS appelle FilterAttach à IRQL = PASSIVE_LEVEL.

Exemples

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

FILTER_ATTACH MyAttach;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

Le type de fonction FILTER_ATTACH 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_ATTACH 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