MINIPORT_CO_OID_REQUEST fonction de rappel (ndis.h)

Article
02/29/2024

La fonction MiniportCoOidRequest gère une requête OID pour interroger ou définir des informations dans le pilote de miniport CoNDIS.

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

Syntaxe

MINIPORT_CO_OID_REQUEST MiniportCoOidRequest;

NDIS_STATUS MiniportCoOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HANDLE MiniportVcContext,
       PNDIS_OID_REQUEST NdisRequest
)
{...}

Paramètres

[in] MiniportAdapterContext

Handle à une zone de contexte que le pilote miniport a allouée dans sa fonction MiniportInitializeEx . Le pilote miniport utilise cette zone de contexte pour conserver les informations d’état d’un adaptateur miniport.

[in] MiniportVcContext

Handle d’une zone de contexte allouée par le pilote miniport dans laquelle le pilote miniport maintient son état de connexion par connexion virtuelle (VC). Le pilote miniport a fourni ce handle à NDIS à partir de sa fonction MiniportCoCreateVc . Si la requête n’est pas spécifique à VC, ce paramètre a la valeur NULL.

NdisRequest

Pointeur vers une structure NDIS_OID_REQUEST qui contient à la fois la mémoire tampon et le paquet de requête que le pilote miniport doit gérer. En fonction de la demande, le pilote retourne les informations demandées dans la structure vers laquelle pointe ce paramètre.

Valeur retournée

MiniportCoOidRequest peut retourner l’une des valeurs de status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	Le pilote miniport a défini ou obtenu les données comme demandé.
NDIS_STATUS_PENDING	Le pilote miniport termine la requête de manière asynchrone. Une fois que le pilote miniport a terminé tout le traitement, il doit appeler le Fonction NdisMCoOidRequestComplete pour informer NDIS que la demande est terminée.
NDIS_STATUS_INVALID_OID	Demande indiquant que le paramètre OidRequest spécifié n’était pas valide ou n’était pas reconnu.
NDIS_STATUS_NOT_SUPPORTED	Demande indiquant que le paramètre OidRequest spécifié a été reconnu, mais pas pris en charge par le pilote miniport.
NDIS_STATUS_BUFFER_TOO_SHORT	La mémoire tampon fournie par le paramètre OidRequest était trop petite pour contenir les données demandées.
NDIS_STATUS_INVALID_LENGTH	La valeur spécifiée dans le membre InformationBufferLength de la structure NDIS_OID_REQUEST sur OidRequest est incorrecte pour le code OID_XXX spécifié.
NDIS_STATUS_INVALID_DATA	Un ou plusieurs des paramètres spécifiés pour la requête sur OidRequest iwas sont non valides.
NDIS_STATUS_NOT_ACCEPTED	Après que NDIS a appelé le Fonction MiniportDevicePnPEventNotify pour indiquer une suppression surprise, NDIS appelle la fonction MiniportHaltEx du pilote. Si le pilote reçoit des requêtes OID avant que NDIS appelle MiniportHaltEx, il doit immédiatement effectuer ces requêtes avec une valeur status de NDIS_STATUS_NOT_ACCEPTED.
NDIS_STATUS_REQUEST_ABORTED	Le pilote miniport a cessé de traiter la demande. Par exemple, NDIS a appelé miniportResetEx ou Fonction MiniportCancelOidRequest .

Remarques

NDIS appelle la fonction MiniportCoOidRequest pour gérer une requête OID afin d’interroger ou de définir des informations dans un pilote miniport CoNDIS.

Pour inscrire MiniportCoOidRequest, les pilotes miniport appellent la fonction NdisSetOptionalHandlers à partir de la fonction MiniportSetOptions . Dans MiniportSetOptions, le pilote miniport initialise un NDIS_MINIPORT_CO_CHARACTERISTICS structure et la transmet au paramètre OptionalHandlers de NdisSetOptionalHandlers.

NDIS appelle la fonction MiniportCoOidRequest soit pour son propre compte, soit pour le compte d’un pilote de protocole lié qui a appelé la fonction NdisCoOidRequest . Les pilotes miniport doivent examiner la demande fournie dans OidRequest et prendre les mesures demandées. Pour plus d’informations sur les OID que les pilotes miniport gèrent, consultez NDIS OID.

Notez que NDIS ne valide pas le contenu spécifique à OID sur OidRequest . Par conséquent, le pilote lui-même doit valider ces contenus. Si le pilote détermine que la valeur à définir est hors limites, il doit échouer la demande et retourner NDIS_STATUS_INVALID_DATA.

Si MiniportCoOidRequest retourne NDIS_STATUS_PENDING, NDIS peut appeler MiniportCoOidRequest avec une autre requête, pour l’adaptateur miniport spécifié dans MiniportAdapterContext, avant que la requête en attente ne soit terminée. NDIS ne sérialise pas les requêtes OID orientées connexion.

Exemples

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

MINIPORT_CO_OID_REQUEST MyCoOidRequest;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HANDLE  MiniportVcContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Le type de fonction MINIPORT_CO_OID_REQUEST 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 MINIPORT_CO_OID_REQUEST 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	<= DISPATCH_LEVEL