Partager via

NdisOpenAdapter, fonction (ndis.h)

  • Article

Remarque NDIS 5. x a été déconseillé et est remplacé par NDIS 6. x. Pour le développement de nouveaux pilotes NDIS, consultez Pilotes réseau à partir de Windows Vista. Pour plus d’informations sur le portage de NDIS 5. pilotes x vers NDIS 6. x, consultez Portage des pilotes NDIS 5.x vers NDIS 6.0.

NdisOpenAdapter configure une liaison entre le protocole appelant et un pilote de carte réseau sous-jacent particulier ou un pilote intermédiaire NDIS.

Syntaxe

void NdisOpenAdapter(
  [out]          PNDIS_STATUS Status,
  [out]          PNDIS_STATUS OpenErrorStatus,
  [out]          PNDIS_HANDLE NdisBindingHandle,
  [out]          PUINT        SelectedMediumIndex,
  [in]           PNDIS_MEDIUM MediumArray,
  [in]           UINT         MediumArraySize,
  [in]           NDIS_HANDLE  NdisProtocolHandle,
  [in]           NDIS_HANDLE  ProtocolBindingContext,
  [in]           PNDIS_STRING AdapterName,
  [in]           UINT         OpenOptions,
  [in, optional] PSTRING      AddressingInformation
);

Paramètres

[out] Status

Pointeur vers une variable fournie par l’appelant qui peut être l’une des valeurs suivantes lors du retour de cette fonction :

  • STATUS_SUCCESS
    La liaison demandée est désormais configurée afin que l’appelant puisse utiliser les valeurs retournées à NdisBindingHandle et SelectedMediumIndex dans les appels suivants à NdisXxx.

  • NDIS_STATUS_PENDING
    L’opération demandée est gérée de manière asynchrone et la fonction ProtocolOpenAdapterComplete de l’appelant est appelée une fois l’ouverture terminée.

  • NDIS_STATUS_RESOURCES
    L’opération demandée a échoué, car NDIS n’a pas pu allouer suffisamment de mémoire ou initialiser l’état qu’il utilise pour suivre une liaison ouverte.

  • NDIS_STATUS_ADAPTER_NOT_FOUND
    L’opération demandée a échoué, car le nom à AdapterName est introuvable dans l’espace de noms de l’objet système.

  • NDIS_STATUS_UNSUPPORTED_MEDIA
    Le tableau à MediumArray n’a pas spécifié de support pris en charge par NDIS ou par le pilote sous-jacent.

  • NDIS_STATUS_CLOSING
    L’appelant ou l’appareil physique ou virtuel désigné à AdapterName est fermé.

  • NDIS_STATUS_OPEN_FAILED
    Échec de la tentative d’ouverture pour aucune des raisons spécifiques précédentes. Par exemple, NDIS n’a peut-être pas pu initialiser le package de filtre pour le support sélectionné.

[out] OpenErrorStatus

Pointeur vers une variable fournie par l’appelant qui peut contenir une erreur NDIS_STATUS_XXX fournissant plus d’informations si NdisOpenAdapter retourne une erreur à Status. Par exemple, le pilote d’une carte réseau d’anneau de jeton peut renvoyer une erreur d’anneau dans cette variable.

[out] NdisBindingHandle

Pointeur vers une variable fournie par l’appelant dans laquelle NDIS retourne un handle représentant une liaison réussie entre l’appelant et la carte réseau physique ou virtuelle donnée spécifiée à AdapterName.

[out] SelectedMediumIndex

Pointeur vers une variable fournie par l’appelant dans laquelle NDIS retourne l’index de l’élément de tableau qui spécifie le type de média utilisé par le pilote NDIS sous-jacent.

[in] MediumArray

Pointeur vers un tableau de valeurs de type NDIS_MEDIUM spécifiant les types de média que l’appelant peut prendre en charge. Les éléments possibles incluent tout sous-ensemble approprié des éléments suivants :

  • NdisMedium802_3
    Spécifie un réseau Ethernet (802.3).

  • NdisMedium802_5
    Spécifie un réseau d’anneau de jeton (802.5).

  • NdisMediumFddi
    Spécifie un réseau FDDI (Fibre Distributed Data Interface).

  • NdisMediumWan
    Spécifie un réseau étendu. Ce type couvre différentes formes de cartes réseau point à point et WAN, ainsi que les formats d’adresse/d’en-tête variant qui doivent être négociés entre le pilote de protocole et le pilote sous-jacent une fois la liaison établie.

  • NdisMediumLocalTalk
    Spécifie un réseau LocalTalk.

  • NdisMediumDix
    Spécifie un réseau Ethernet pour lequel les pilotes utilisent le format d’en-tête ETHERNET DIX.

  • NdisMediumArcnetRaw
    Spécifie un réseau ARCNET.

  • NdisMediumArcnet878_2
    Spécifie un réseau ARCNET (878.2).

  • NdisMediumAtm
    Spécifie un réseau ATM. Les protocoles clients orientés connexion peuvent se lier à un pilote miniport sous-jacent qui retourne cette valeur. Dans le cas contraire, les protocoles hérités se lient au pilote intermédiaire LanE fourni par le système, qui signale son type moyen comme NdisMedium802_3 ou NdisMedium802_5, selon la façon dont le pilote LanE est configuré par l’administrateur réseau.

  • NdisMediumWirelessWan
    Spécifie un réseau sans fil. Les pilotes miniport NDIS 5.X qui prennent en charge les paquets RÉSEAU local sans fil (WLAN) ou WWAN (Wireless WAN) déclarent leur support comme NdisMedium802_3 et émulent Ethernet vers des pilotes NDIS de niveau supérieur.

    Remarque Ce type de média n’est pas disponible pour une utilisation à partir de Windows Vista.

  • NdisMediumIrda
    Spécifie un réseau infrarouge (IrDA).

  • NdisMediumCoWan
    Spécifie un réseau étendu dans un environnement orienté connexion.

  • NdisMedium1394
    Spécifie un réseau IEEE 1394 (câble d’incendie).

[in] MediumArraySize

Spécifie le nombre d’éléments à MediumArray.

[in] NdisProtocolHandle

Spécifie le handle retourné par NdisRegisterProtocol.

[in] ProtocolBindingContext

Spécifie le handle d’une zone de contexte résident fournie par l’appelant dans laquelle le protocole conserve l’état de cette liaison une fois qu’elle a été établie.

[in] AdapterName

Pointeur vers un type NDIS_STRING contenant une chaîne comptée, spécifié dans le jeu de caractères par défaut du système, nommant la carte réseau ou l’adaptateur virtuel d’un pilote NDIS sous-jacent. Ce pilote exporte un ensemble de fonctions supérieures (MiniportXxx). Pour les pilotes Windows 2000 et versions ultérieures, cette chaîne comptée contient des caractères Unicode. Autrement dit, pour Windows 2000 et versions ultérieures, NDIS définit le type NDIS_STRING en tant que type UNICODE_STRING.

[in] OpenOptions

Spécifie un masque de bits contenant des indicateurs que l’appelant passe au pilote inférieur suivant, supposé être un pilote de carte réseau. Actuellement, ce paramètre est réservé à l’utilisation du système.

[in, optional] AddressingInformation

Pointeur vers une chaîne facultative comptée de longueur variable contenant des informations spécifiques à la carte réseau sous-jacente que le pilote de carte réseau peut utiliser pour programmer la carte réseau. Ce pointeur peut être NULL.

S’il est fourni, les informations d’adressage doivent rester valides jusqu’à ce que l’opération ouverte se termine. Un pilote de carte réseau sous-jacent qui prend en charge un modem asynchrone peut utiliser ces informations pour la numérotation.

Valeur de retour

Aucun

Remarques

Un pilote de protocole appelle NdisOpenAdapter à partir de sa fonction ProtocolBindAdapter. NDIS ne prend plus en charge l’appel NdisOpenAdapter à partir de la fonction DriverEntry, qui était une option disponible pour les protocoles hérités (V3.0). NDIS ne prend plus en charge les protocoles V3.0. NDIS échoue toute tentative d’appel NdisOpenAdapter en dehors du contexte de ProtocolBindAdapter.

La chaîne à AdapterName reste valide uniquement jusqu’à ce que NdisOpenAdapter retourne le contrôle, même s’il retourne NDIS_STATUS_PENDING au Status.

Les variables à NdisBindingHandle et SelectedMediumIndex doivent être ignorées jusqu’à ce que la fonction ProtocolOpenAdapterComplete soit appelée si NdisOpenAdapter retourne NDIS_STATUS_PENDING. Étant donné que ces variables peuvent rester non valides tant que ProtocolOpenAdapterComplete est appelée, elles ne peuvent pas se trouver sur la pile. En règle générale, ces variables résident dans la zone ProtocolBindingContext, car ce handle est un paramètre d’entrée pour ProtocolOpenAdapterComplete.

Un pilote de protocole doit conserver le handle retourné à NdisProtocolHandle. Il s’agit d’un paramètre obligatoire pour d’autres fonctions NdisXxx que le pilote appelle par la suite. Le ProtocolBindingContext fourni est un paramètre d’entrée des fonctions ProtocolXxx protocolXxx de l’appelant. Les protocoles passent donc généralement un pointeur NdisProtocolHandle vers une variable quelque part dans la zone de contexte allouée par l’appelant dans leurs appels à NdisOpenAdapter.

L’appelant utilise la valeur retournée à SelectedMediumIndex dans les appels suivants à NdisRequest et/ou NdisCoRequest. Les OID qu’il définit dans le paquet de requête dépendent du NdisMediumXxx retourné. Par exemple, si NdisMediumAtm est retourné à SelectedMediumIndex, le pilote de protocole appelle NdisCoRequest lors de la spécification de codes OID_ATM_ XXX ou OID_CO_XXX et NdisRequest lors de la spécification de codes OID_GEN_XXX.

Si NdisMediumWan est retourné à SelectedMediumIndex, le pilote de protocole appelle NdisRequest en spécifiant OID_WAN_MEDIUM_SUBTYPE dans une requête pour déterminer quels types de supports WAN le pilote sous-jacent utilise.

Si une requête globale précédemment émise de OID_NETWORK_TYPE pour le support sans fil indique que le pilote et la carte réseau sous-jacente prennent en charge plusieurs NdisMediumWirelessWan-type moyen, le protocole doit sélectionner l’un des supports pris en charge dès que NDIS a configuré la liaison et avant que le protocole sélectionne le format d’en-tête.

Pour plus d’informations sur les OI généraux et spécifiques à un support que les pilotes de protocole utilisent pour négocier avec un pilote NDIS à liaison juste, consultez identificateurs d’objets NDIS.

  • Plateforme cible : universelle
  • Version : non pris en charge pour les pilotes NDIS 6.0 dans Windows Vista. Utilisez NdisOpenAdapterExà la place. Pris en charge pour les pilotes NDIS 5.1 dans Windows Vista et Windows XP.

Exigences

Exigence Valeur
d’en-tête ndis.h (include Ndis.h)
bibliothèque Ndis.lib
IRQL PASSIVE_LEVEL

Voir aussi