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 miniports, 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 du pilote ( NdisMRegisterMiniportDriver pour les pilotes miniports, 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, Protocol ou Filter).
Valeur de retour
XxxSetOptions retourne l’une des valeurs d’état suivantes :
| Retourner le code | Description |
|---|---|
|
XxxSetOptions inscrit correctement 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, un tel état d’erreur est propagé à partir d’une Ndisfonction xxx 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 au NdisRegisterXxxDriver fonction, 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, ProtocolXxxou fonctions 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 documentation sur le déchargement de cheminée TCP NDIS 6.0)
- NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(consultez 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, ProtocolXxxou Fonctions FilterXxx à tout moment après XxxSetOptions. Le pilote doit être prêt à être rappelé à sa fonction d’initialisation :(MiniportInitializeEx pour les pilotes miniports, ProtocolBindAdapterEx pour les pilotes de protocole et FilterAttach pour les pilotes de filtre).
Pour les pilotes miniports, les adaptateurs miniport sont dans l’état arrêté avant que le NDIS appelle MiniportInitializeEx. Pour les pilotes de protocole, les liaisons de protocole sont dans l’état non lié avant que le NDIS appelle ProtocolBindAdapterEx. Pour les pilotes de filtre, les modules de filtre sont dans 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 retourne le contrôle avec un état autre que NDIS_STATUS_SUCCESS.
Les pilotes miniport et filtrent XxxDriverUnload doivent annuler toutes les opérations effectuées dans XxxSetOptions
NDIS appelle XxxSetOptions à IRQL = PASSIVE_LEVEL.
exemples de
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 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.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 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 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 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 |