Partager via

NdisMSetAttributesEx, 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.

NdisMSetAttributesEx informe la bibliothèque NDIS sur les 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 pour 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 demande OID ou envoyé une demande au cours de deux appels successifs à MiniportCheckForHang, NDIS peut appeler la fonction MiniportReset du pilote.

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

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

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 dispose de ressources insuffisantes pour transmettre immédiatement un envoi entrant.

[in] AttributeFlags

Spécifie un masque de bits qui peut être défini avec un ou plusieurs (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 en attente qu’il contient mis en file d’attente à l’appelant. Les pilotes intermédiaires doivent définir cet indicateur, mais les pilotes de carte réseau ne doivent pas.

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

  • 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 miniportRes et du pilote 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 alimentation (veille). Les pilotes qui s’appuient sur l’état géré par le matériel ne doivent pas définir cet indicateur.

    Remarque Paramètre de cet indicateur désactive l'Autoriser l’ordinateur à désactiver cet appareil pour enregistrer l’alimentation case à cocher dans l’onglet Gestion de l’alimentation de la boîte de dialogue Propriétés de la carte d’interface réseau(NIC). 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 de l’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, NdisGetFirstBufferFromPacketSafeet 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 besoin de mapper les mémoires tampons de paquets 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 NDIS TAPI (NPDROXY). Par défaut, NDIS lie NPDROXY à 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 l’une des opérations suivantes :

  • 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 (Périphérique Component Interconnect).

  • NdisInterfacePcMcia
    Spécifie l’interface de l’Association internationale de la carte mémoire de l’ordinateur personnel (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

Aucun

Remarques

Une fonction miniportInitializedoit appeler NdisMSetAttributesEx(ou NdisMSetAttributes) avant d’appeler une autre fonction NdisMRegisterXxx ou NdisXxx qui dépend des informations fournies à NdisMSetAttributesEx. Par exemple, l’appel d’un pilote de carte réseau à NdisMAllocateMapRegisters échoue si MiniportInitialize n’a pas encore appelé NdisMSetAttributesEx avec le AttributeFlags défini 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 le AttributeFlags. Si vous définissez cet indicateur, NDIS traite un pilote intermédiaire comme un pilote miniport full-duplex, ce qui empêche les blocages rares mais intermittents de se produire dans le pilote intermédiaire. Par conséquent, chaque pilote intermédiaire doit être capable de gérer les envois et indications simultanés.

Les pilotes désérialisés doivent également appeler NdisMSetAttributesEx, et ils doivent définir NDIS_ATTRIBUTE_DESERIALIZE dans le 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 à un tel pilote fonctions miniportXxx. Un pilote désérialisé se rend responsable des éléments suivants :

  • Acceptation de toutes les demandes d’envoi entrantes
  • Mise en file d’attente des paquets d’envoi entrants en interne si nécessaire, par exemple si un pilote de carte réseau désérialisé dispose actuellement de ressources insuffisantes pour transmettre immédiatement un paquet d’envoi entrant
  • Synchronisation de l’accès à ses files d’attente internes en fonction des besoins des routines du pilote
  • Fin de tous les envois demandés de manière asynchrone en appelant par la suite 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, quel que soit le 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 carte réseau sérialisées peuvent appeler l’une de ces fonctions à partir de MiniportInitialize, mais NdisMSetAttributes n’autorise pas son appelant à ajuster l’intervalle auquel les MiniportCheckForHang et/ou MiniportReset function(s) 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 sur les envois, le cas échéant, et les demandes qu’elle contient en file d’attente à l’appelant. Par défaut, NDIS expire les envois mis en file d’attente (uniquement pour les pilotes sérialisés) et les demandes à deux reprises à l’intervalle d’archivage, 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 ce pilote ne peut pas déterminer ou contrôler quand le pilote de carte réseau sous-jacent traite 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 cette spécification par un pilote de carte réseau sérialisé. 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 suppose 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 son MiniportCheckForHang fonction, le cas échéant, est appelé pour tester l’état opérationnel de la carte réseau.

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

Un pilote miniport hérité qui gère une carte réseau non prenant en charge PnP peut définir l’indicateur de NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND pour empêcher le pilote d’arrêter le pilote avant que le système passe à un état à faible alimentation. 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 peut avoir indiqué que la carte réseau n’est pas prenant en charge 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 d’appareil de NdisDeviceStateUnspecified pour chaque fonctionnalité de mise en éveil. Lorsque le système passe à un état à faible alimentation, NDIS n’appelle pas la fonction MiniportHalt d’un pilote miniport. Avant que le système passe à un état d’alimentation inférieur, le pilote miniport doit enregistrer tout contexte matériel qu’il conserve. 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 à faible alimentation. 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 travail.

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. Cela entraîne l’appel de la fonction MiniportPnPEventNotify du pilote avec Fonction PnPEvent définie sur NdisDevicePnPEventSurpriseRemoved lorsque l’appareil du miniport est supprimé sans notification. En outre, définir 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 par erreur que son appareil est orienté connexion, car le pilote inscrit les fonctions de pilote miniport orienté connexion avec NdisMRegisterMiniport.

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

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

Le handle miniportAdapterContext fourni à NdisMSetAttributesEx devient un paramètre d’entrée pour toutes les fonctions MiniportXxx inscrites, ainsi que 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é par MiniportInitialize, dans lequel le pilote gère 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.

Exigences

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

Voir aussi