SET_OPTIONS fonction de rappel (ndis.h)
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.
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 |
|---|---|
|
XxxSetOptions a correctement inscrit les services et ressources facultatifs du pilote. |
|
XxxSetOptions n’a pas pu allouer les ressources dont le pilote a besoin. |
|
É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);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 |