NdisMSetAttributesEx, fonction (ndis.h)

  • Article

Note 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. x pilotes dans NDIS 6. x, consultez Portage des pilotes NDIS 5.x vers NDIS 6.0.

NdisMSetAttributesEx informe la bibliothèque NDIS des fonctionnalités importantes de la carte réseau ou de la carte réseau virtuelle de l’appelant lors de l’initialisation.

Syntaxe

void NdisMSetAttributesEx(
  [in]           NDIS_HANDLE         MiniportAdapterHandle,
  [in]           NDIS_HANDLE         MiniportAdapterContext,
  [in, optional] UINT                CheckForHangTimeInSeconds,
  [in]           ULONG               AttributeFlags,
  [in, optional] NDIS_INTERFACE_TYPE AdapterType
);

Paramètres

[in] MiniportAdapterHandle

Spécifie l’entrée de handle dans MiniportInitialize.

[in] MiniportAdapterContext

Spécifie un handle pour une zone de contexte résidente allouée par MiniportInitialize.

[in, optional] CheckForHangTimeInSeconds

Spécifie l’intervalle, en secondes, auquel NDIS doit appeler la fonction MiniportCheckForHang . Si un pilote n’a pas répondu à une requête OID ou envoyé une requête au cours de deux appels successifs à MiniportCheckForHang, NDIS peut appeler la fonction MiniportReset du pilote.

L’intervalle réel utilisé par NDIS lors de l’appel de MiniportCheckForHang est toujours un multiple de 2 secondes. Par exemple, si vous spécifiez 5 secondes, l’intervalle réel sera d’environ 4 secondes.

La spécification de zéro pour ce paramètre indique que NDIS doit appeler MiniportCheckForHang à l’intervalle NDIS par défaut de 2 secondes.

Si l’appelant définit NDIS_ATTRIBUTE_DESERIALIZE dans AttributeFlags, NDIS ne met pas en file d’attente les envois en attente pour le pilote miniport. Au lieu de cela, un tel pilote désérialisé doit gérer sa propre mise en file d’attente des demandes d’envoi suivantes en interne chaque fois qu’il ne dispose pas de ressources suffisantes pour transmettre immédiatement un envoi entrant.

[in] AttributeFlags

Spécifie un masque de bits qui peut être défini avec un ou plusieurs indicateurs (ORed) des indicateurs suivants :

  • NDIS_ATTRIBUTE_BUS_MASTER
    Définissez si la carte réseau de l’appelant est un appareil DMA maître de bus.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Définissez si l’appelant est un pilote miniport désérialisé.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Définissez si NDIS ne doit pas tenter d’expirer les paquets d’envoi qu’il conserve en file d’attente vers l’appelant. Les pilotes intermédiaires doivent définir cet indicateur, mais pas les pilotes de carte réseau.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Définissez si NDIS ne doit pas tenter d’expirer la requête en attente et définissez les demandes qu’il conserve en file d’attente pour l’appelant. Les pilotes intermédiaires doivent définir cet indicateur, mais pas les pilotes de carte réseau.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Définissez si l’appelant est un pilote intermédiaire.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Définissez si NDIS ne doit pas appeler la fonction MiniportReset d’un pilote de carte réseau d’anneau de jeton si des erreurs d’anneau de jeton sont indiquées.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Définissez si NDIS ne doit pas appeler la fonction MiniportHalt d’un pilote avant que le système passe à un état de faible consommation (mise en veille). Les pilotes qui s’appuient sur un état géré par le matériel ne doivent pas définir cet indicateur.

    Note La définition de cet indicateur désactive la case à cocher Autoriser l’ordinateur à désactiver cet appareil pour économiser l’alimentation sous l’onglet Gestion de l’alimentation de la boîte de dialogue Propriétés de la carte d’interface réseau . La gestion de l’alimentation est désactivée même si la carte réseau est capable de gérer l’alimentation.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Définissez si le pilote peut gérer la suppression de sa carte réseau sans notification utilisateur. Un tel pilote exporte une fonction MiniportPnPEventNotify . La prise en charge du système pour NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK est disponible dans Windows XP et les systèmes d’exploitation ultérieurs.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Défini par un pilote qui peut prendre en charge les appareils orientés connexion et sans connexion pour indiquer que l’appareil est un appareil sans connexion. La prise en charge du système pour NDIS_ATTRIBUTE_NOT_CO_NDIS est disponible dans Windows XP et les systèmes d’exploitation ultérieurs.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Défini par un pilote qui utilise NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe et NdisQueryBufferSafe exclusivement pour accéder aux adresses virtuelles système pour envoyer des mémoires tampons de paquets. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS est également défini par un pilote qui utilise exclusivement des adresses physiques pour accéder à ces mémoires tampons. La définition de NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS peut améliorer les performances, car le système d’exploitation n’aura pas à mapper les mémoires tampons de paquets d’envoi aux adresses virtuelles système. La prise en charge du système pour NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS est disponible dans Windows XP et versions ultérieures.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Défini par un pilote miniport CoNDIS qui ne fournit pas de services TAPI. La définition NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO empêche NDIS de lier le pilote miniport au pilote proxy TAPI NDIS (NDPROXY). Par défaut, NDIS lie NDPROXY à tous les pilotes miniport CoNDIS.

[in, optional] AdapterType

Spécifie le type d’interface de bus d’E/S de la carte réseau de l’appelant, qui est généralement le type de bus d’E/S sur lequel la carte réseau est connectée, comme suit :

  • NdisInterfaceInternal
    Spécifie une interface interne spécifique à l’hôte.

  • NdisInterfaceIsa
    Spécifie l’interface ISA.

  • NdisInterfaceEisa
    Spécifie l’interface ISA étendue (EISA).

  • NdisInterfaceMca
    Cela fait référence au bus MCA, qui n’est plus pris en charge.

  • NdisInterfaceTurboChannel
    Spécifie l’interface Turbo Channel.

  • NdisInterfacePci
    Spécifie l’interface PCI (Peripheral Component Interconnect).

  • NdisInterfacePcMcia
    Spécifie l’interface Personal Computer Memory Card International Association (CARTE PC).

Ce paramètre n’est pas pertinent pour les pilotes intermédiaires, qui doivent passer zéro pour cet argument à NdisMSetAttributesEx.

Valeur de retour

None

Remarques

Une fonction MiniportInitialize doit appeler NdisMSetAttributesEx(ou NdisMSetAttributes) avant d’appeler toute autre fonction NdisMRegisterXxx ou NdisXxx qui dépend des informations fournies à NdisMSetAttributesEx. Par exemple, l’appel d’un pilote de carte réseau à NdisMAllocateMapRegisters échouera si MiniportInitialize n’a pas encore appelé NdisMSetAttributesEx avec les AttributeFlags définis avec NDIS_ATTRIBUTE_BUS_MASTER.

Les pilotes intermédiaires doivent appeler NdisMSetAttributesEx, plutôt que NdisMSetAttributes, et ils doivent définir NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER dans attributeFlags. La définition de cet indicateur amène NDIS à traiter un pilote intermédiaire comme un pilote miniport full duplex, ce qui empêche les interblocages rares mais intermittents de se produire dans le pilote intermédiaire. Par conséquent, chaque pilote intermédiaire doit être capable de gérer des envois et des indications simultanés.

Les pilotes désérialisés doivent également appeler NdisMSetAttributesEx, et ils doivent définir NDIS_ATTRIBUTE_DESERIALIZE dans attributeFlags. NDIS ne gère pas de file d’attente de paquets d’envoi pour un pilote désérialisé, ni NDIS sérialise les appels aux fonctions MiniportXxx d’un tel pilote. Un pilote désérialisé se rend responsable des éléments suivants :

  • Acceptation de toutes les demandes d’envoi entrantes
  • La mise en file d’attente des paquets d’envoi entrants s’effectue en interne si nécessaire, comme, par exemple, si un pilote de carte réseau désérialisé ne dispose actuellement pas de ressources suffisantes pour transmettre immédiatement un paquet d’envoi entrant
  • Synchronisation de l’accès à ses files d’attente internes si nécessaire parmi les routines du pilote
  • Terminer toutes les envois demandés de manière asynchrone en appelant ensuite NdisMSendComplete avec chaque descripteur de paquet fourni par le protocole passé à sa fonction Miniport(Co)Send(Packets)

NDIS suppose que tous les miniports orientés connexion sont des pilotes désérialisés, quels que soient les AttributeFlags qu’ils passent à NdisMSetAttributesEx. Autrement dit, tout pilote qui appelle NdisMRegisterMiniport avec 0x05 comme MajorNdisVersion doit être un pilote miniport désérialisé.

Les pilotes de cartes réseau sérialisées peuvent appeler l’une de ces fonctions à partir de MiniportInitialize, mais NdisMSetAttributes ne permet pas à son appelant d’ajuster l’intervalle auquel les fonctions MiniportCheckForHang et/ou MiniportReset d’un pilote de carte réseau sont appelées.

La valeur de CheckForHangTimeInSeconds détermine l’intervalle de délai d’attente de la bibliothèque NDIS à l’envoi, le cas échéant, et demande qu’elle conserve en file d’attente à l’appelant. Par défaut, NDIS délait les envois en file d’attente (uniquement pour les pilotes sérialisés) et les demandes à deux fois l’intervalle check-for-hang, après quoi il appelle la fonction MiniportReset , sauf si le pilote définit AttributeFlags avec NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT et NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT lorsqu’il appelle NdisMSetAttributesEx. Les pilotes intermédiaires doivent définir ces indicateurs lors de l’appel de NdisMSetAttributesEx , car un tel pilote ne peut pas déterminer ou contrôler quand le pilote de carte réseau sous-jacent traitera les envois et les demandes.

Les pilotes de carte réseau ne doivent pas définir les indicateurs NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT et NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT, bien que NDIS respecte une telle spécification par un pilote de carte réseau sérialisée. Toutefois, les pilotes de carte réseau peuvent ajuster l’intervalle de délai d’attente auquel leurs fonctions MiniportReset sont appelées en spécifiant un CheckForHangTimeInSeconds explicite. Par exemple, un pilote de carte réseau qui émule Ethernet sur un modem peut ne pas terminer chaque paquet dans l’intervalle de délai d’attente par défaut de la bibliothèque NDIS. Chaque fois qu’un paquet semblait expirer sur une telle carte réseau, NDIS supposait que la carte réseau ne fonctionnait plus correctement et appelait la fonction MiniportReset du pilote. Pour le pilote d’une telle carte réseau, l’appel de NdisMSetAttributesEx avec un CheckForHangTimeInSeconds défini sur une valeur supérieure à deux empêche les réinitialisations inutiles et étend l’intervalle auquel sa fonction MiniportCheckForHang , le cas échéant, est appelée pour tester l’état opérationnel de la carte réseau.

Un pilote intermédiaire doit définir l’indicateur NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND. La définition de cet indicateur empêche NDIS d’arrêter le pilote avant que le système passe à un état de faible consommation (veille).

Un pilote miniport hérité qui gère une carte réseau non compatible PnP peut définir l’indicateur de NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND pour empêcher NDIS d’arrêter le pilote avant que le système ne passe à un état de faible consommation. Si le pilote miniport définit cet indicateur, NDIS interroge le pilote miniport avec OID_PNP_CAPABILITIES même si le pilote de bus pour la carte réseau du pilote miniport a peut-être indiqué que la carte réseau ne prend pas en charge le pm. Le pilote miniport doit réussir la demande de OID_PNP_CAPABILITIES avec NDIS_STATUS_SUCCESS. Dans la structure NDIS_PM_WAKE_UP_CAPABILITIES retournée par cet OID, le pilote miniport doit également spécifier un état d’alimentation du périphérique NdisDeviceStateUnspecified pour chaque fonctionnalité de mise en éveil. Lorsque le système passe à un état de faible consommation, NDIS n’appelle pas la fonction MiniportHalt d’un pilote miniport de ce type. Avant que le système passe à un état d’alimentation inférieure, le pilote miniport doit enregistrer tout contexte matériel qu’il gère. Lors de la réception d’une demande de OID_PNP_SET_POWER à l’état D3, le pilote miniport doit définir sa carte réseau sur l’état approprié pour l’état de faible consommation. Lors de la réception d’une demande de OID_PNP_SET_POWER à l’état D0, le pilote miniport doit définir sa carte réseau sur l’état approprié pour l’état de fonctionnement.

Un pilote miniport qui prend en charge la suppression surprise de son appareil (suppression sans notification via l’interface utilisateur) doit définir NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK. Ainsi, NDIS appelle la fonction MiniportPnPEventNotify du pilote avec PnPEvent défini sur NdisDevicePnPEventSurpriseRemoved lorsque l’appareil du miniport est supprimé sans notification. En outre, la définition de NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK supprime l’affichage d’une boîte de dialogue d’avertissement qui demande à l’utilisateur d’arrêter l’appareil avant de le supprimer.

Un pilote miniport qui peut prendre en charge les appareils sans connexion et orientés connexion doit définir NDIS_ATTRIBUTE_NOT_CO_NDIS si son appareil est un appareil sans connexion. Sinon, NDIS suppose à tort que son appareil est orienté connexion, car le pilote enregistre les fonctions de pilote miniport orientée connexion auprès de NdisMRegisterMiniport.

En général, un pilote de carte réseau doit appeler NdisMSetAttributesEx avant d’appeler une fonction NdisXxx qui réclame des ressources matérielles dans le Registre pour sa carte réseau, car NDIS doit avoir la valeur AttributeFlags avant d’effectuer un tel appel et parce que le pilote a généralement besoin de la mémoire sur MiniportAdapterContext pour stocker les informations pour ces appels. Cette restriction implique que la fonction MiniportInitialize d’un pilote de carte réseau ne peut pas appeler le NdisXxx suivant avant d’appeler NdisMSetAttributesEx :

Toutefois, avant d’appeler NdisMSetAttributesEx, la fonction MiniportInitialize d’un pilote peut appeler le Ndis.. Fonctions de configuration pour récupérer les informations de configuration installées dans le Registre. MiniportInitialize peut également appeler les fonctions NdisReadXxx spécifiques au type de bus, telles que NdisReadPciSlotInformation, tant que l’entrée de Registre installée pour le type d’interface du pilote correspond aux appels NdisReadXxxMiniportInitialize spécifiques au type de bus.

Le handle MiniportAdapterContext fourni à NdisMSetAttributesEx devient un paramètre d’entrée pour toutes les fonctions MiniportXxx qui ont été inscrites, avec MiniportInitialize, dans l’appel à NdisMRegisterMiniport ou NdisIMRegisterLayeredMiniport. En règle générale, ce handle est un pointeur vers la mémoire résidente, allouée par MiniportInitialize, dans laquelle le pilote maintient l’état d’exécution spécifique à la carte réseau.

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

Configuration requise

Condition requise Valeur
En-tête ndis.h (inclure Ndis.h)
Bibliothèque Ndis.lib
IRQL PASSIVE_LEVEL

Voir aussi