SET_OPTIONS fonction de rappel (ndis.h)

Article
08/07/2023

NDIS appelle la fonction XxxSetOptions d’un pilote pour permettre au pilote d’inscrire des services facultatifs. Cette fonction est définie comme MiniportSetOptions pour les pilotes miniport, ProtocolSetOptions pour les pilotes de protocole ou FilterSetOptions pour les pilotes de filtre.

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

Syntaxe

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

Paramètres

[in] NdisDriverHandle

Handle qui identifie un pilote. NDIS retourne ce handle au pilote lorsqu’il retourne à partir de la fonction d’inscription de pilote ( NdisMRegisterMiniportDriver pour les pilotes miniport, NdisRegisterProtocolDriver pour les pilotes de protocole et NdisFRegisterFilterDriver pour les pilotes de filtre).

[in] DriverContext

Handle que le pilote a passé à NdisRegisterXxxDriver qui identifie la zone de contexte du pilote, où Xxx est le type de pilote (Miniport, Protocole ou Filtre).

Valeur retournée

XxxSetOptions retourne l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	XxxSetOptions a correctement inscrit les services et ressources facultatifs du pilote.
NDIS_STATUS_RESOURCES	XxxSetOptions n’a pas pu allouer les ressources dont le pilote a besoin.
NDIS_STATUS_XXX ou NTSTATUS_XXX	Échec de la tentative d’inscription des options du pilote. En règle générale, une telle erreur status est propagée à partir d’une fonction NdisXxx ou d’une routine de prise en charge en mode noyau.

Remarques

XxxSetOptions est une fonction facultative. NDIS appelle XxxSetOptions dans le contexte de l’appel du pilote à Fonction NdisRegisterXxxDriver , où Xxx est le type de pilote (Miniport, Protocol ou Filter).

XxxSetOptions inscrit des services facultatifs et peut allouer d’autres ressources de pilote. Pour inscrire des fonctions Facultatives MiniportXxx, ProtocolXxx ou FilterXxx , le pilote appelle la fonction NdisSetOptionalHandlers . Le pilote transmet le handle du paramètre NdisDriverHandle au paramètre NdisHandle de NdisSetOptionalHandlers et transmet une structure de caractéristiques au paramètre OptionalHandlers .

Les pilotes Miniport peuvent s’appliquer aux services facultatifs définis dans les structures de caractéristiques suivantes :

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(consultez la documentation sur le déchargement de cheminée TCP NDIS 6.0)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(consultez la documentation sur le déchargement de cheminée TCP NDIS 6.0)

Les pilotes de protocole peuvent s’appliquer aux services facultatifs définis dans les structures de caractéristiques suivantes :

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

Il n’existe aucun service de pilote de filtre facultatif dans la version actuelle de Windows.

NDIS peut appeler les autres fonctions MiniportXxx, ProtocolXxx ou FilterXxx du pilote à tout moment après le retour de XxxSetOptions . Le pilote doit être prêt à être rappelé à sa fonction d’initialisation :(MiniportInitializeEx pour les pilotes miniport, ProtocolBindAdapterEx pour les pilotes de protocole et FilterAttach pour les pilotes de filtre).

Pour les pilotes miniport, les adaptateurs miniport sont à l’état Arrêté avant que le NDIS appelle MiniportInitializeEx. Pour les pilotes de protocole, les liaisons de protocole sont à l’état Unbound avant que NDIS appelle ProtocolBindAdapterEx. Pour les pilotes de filtre, les modules de filtre sont à l’état Détaché avant que le NDIS appelle FilterAttach.

Si une tentative d’allocation de ressources ou de services échoue, XxxSetOptions doit annuler toutes les allocations qui ont réussi avant qu’elle ne retourne le contrôle avec un status autre que NDIS_STATUS_SUCCESS.

XxxDriverUnload des pilotes miniport et filtre doit annuler toutes les opérations effectuées dans XxxSetOptions

NDIS appelle XxxSetOptions à IRQL = PASSIVE_LEVEL.

Exemples

Pour définir une fonction XxxSetOptions , 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.

Dans le fichier d’en-tête Ndis.h, la fonction de rappel SET_OPTIONS est définie comme suit :

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

Cela permet à tous les pilotes NDIS d’implémenter leurs fonctions de rappel XxxSetOptions avec la même syntaxe. Les pilotes miniport utilisent le type MINIPORT_SET_OPTIONS , les pilotes de protocole utilisent le type PROTOCOL_SET_OPTIONS et les pilotes de filtre utilisent le type FILTER_SET_OPTIONS .

Par exemple, pour définir une fonction MiniportSetOptions nommée « MySetOptions », utilisez le type MINIPORT_SET_OPTIONS comme indiqué dans cet exemple de code :

MINIPORT_SET_OPTIONS MySetOptions;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

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