NdisMSetAttributesEx-Funktion (ndis.h)

  • Artikel

Hinweis NDIS 5. x ist veraltet und wird durch NDIS 6 ersetzt. x. Informationen zur Entwicklung neuer NDIS-Treiber finden Sie unter Netzwerktreiber ab Windows Vista. Informationen zum Portieren von NDIS 5. x Treiber für NDIS 6. x, siehe Portieren von NDIS 5.x-Treibern zu NDIS 6.0.

NdisMSetAttributesEx informiert die NDIS-Bibliothek über wichtige Features der NIC oder virtuellen NIC des Aufrufers während der Initialisierung.

Syntax

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

Parameter

[in] MiniportAdapterHandle

Gibt die Handle-Eingabe für MiniportInitialize an.

[in] MiniportAdapterContext

Gibt ein Handle für einen von MiniportInitialize zugewiesenen residenten Kontextbereich an.

[in, optional] CheckForHangTimeInSeconds

Gibt das Intervall in Sekunden an, in dem NDIS die MiniportCheckForHang-Funktion aufrufen soll. Wenn ein Treiber innerhalb von zwei aufeinander folgenden Aufrufen von MiniportCheckForHang nicht auf eine OID-Anforderung reagiert oder eine Anforderung gesendet hat, kann NDIS die MiniportReset-Funktion des Treibers aufrufen.

Das tatsächliche Intervall, das NDIS beim Aufrufen von MiniportCheckForHang verwendet, ist immer ein Vielfaches von 2 Sekunden. Wenn Sie beispielsweise 5 Sekunden angegeben haben, beträgt das tatsächliche Intervall ungefähr 4 Sekunden.

Die Angabe von null für diesen Parameter gibt an, dass NDIS MiniportCheckForHang im NDIS-Standardintervall von 2 Sekunden aufrufen sollte.

Wenn der Aufrufer NDIS_ATTRIBUTE_DESERIALIZE in AttributeFlags festlegt, führt NDIS keine warteschlangenstehenden Senden für den Miniporttreiber aus. Stattdessen muss ein solcher deserialisierter Treiber seine eigene Warteschlangen für nachfolgende Sendeanforderungen intern verwalten, wenn er über ausreichende Ressourcen verfügt, um einen eingehenden Sendevorgang sofort zu übertragen.

[in] AttributeFlags

Gibt eine Bitmaske an, die mit mindestens einem (ORed) der folgenden Flags festgelegt werden kann:

  • NDIS_ATTRIBUTE_BUS_MASTER
    Legen Sie fest, ob die NIC des Aufrufers ein Bus-master DMA-Gerät ist.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Legen Sie fest, ob der Aufrufer ein deserialisierter Miniporttreiber ist.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Legen Sie fest, ob NDIS nicht versuchen soll, ausstehende Sendepakete in der Warteschlange für den Aufrufer zu timeouten. Zwischentreiber sollten dieses Flag festlegen, NIC-Treiber jedoch nicht.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Legen Sie fest, ob NDIS nicht versuchen soll, ein Timeout für ausstehende Abfragen auszuführen, und legen Sie anforderungen, die in der Warteschlange enthalten sind, an den Aufrufer fest. Zwischentreiber sollten dieses Flag festlegen, NIC-Treiber jedoch nicht.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Legen Sie fest, ob der Aufrufer ein Zwischentreiber ist.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Legen Sie fest, ob NDIS die MiniportReset-Funktion eines Token Ring-NIC-Treibers nicht aufrufen soll, wenn Token ring-Fehler angezeigt werden.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Legen Sie fest, ob NDIS die MiniportHalt-Funktion eines Treibers nicht aufrufen soll, bevor das System in einen Zustand mit geringer Leistung (Ruhezustand) wechselt. Treiber, die auf dem Hardwarezustand basieren, sollten dieses Flag nicht festlegen.

    Hinweis Durch Festlegen dieses Flags wird das Kontrollkästchen Stromsparen dieses Geräts auf der Registerkarte Energieverwaltung des Dialogfelds Eigenschaften für die Netzwerkschnittstelle Karte (NIC) deaktiviert. Die Energieverwaltung ist deaktiviert, auch wenn die NIC energieverwaltungsfähig ist.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Legen Sie fest, ob der Treiber das Entfernen seiner NIC ohne Benutzerbenachrichtigung verarbeiten kann. Ein solcher Treiber exportiert eine MiniportPnPEventNotify-Funktion . Die Systemunterstützung für NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK ist unter Windows XP und höheren Betriebssystemen verfügbar.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Wird von einem Treiber festgelegt, der sowohl verbindungsorientierte als auch verbindungslose Geräte unterstützen kann, um anzugeben, dass es sich bei dem Gerät um ein verbindungsloses Gerät handelt. Die Systemunterstützung für NDIS_ATTRIBUTE_NOT_CO_NDIS ist unter Windows XP und höheren Betriebssystemen verfügbar.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Legen Sie durch einen Treiber fest, der NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe und NdisQueryBufferSafe ausschließlich für den Zugriff auf virtuelle Systemadressen für Sendepaketpuffer verwendet. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS wird auch von einem Treiber festgelegt, der ausschließlich physische Adressen für den Zugriff auf solche Puffer verwendet. Das Festlegen NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS kann die Leistung verbessern, da das Betriebssystem keine Paketpuffer zu virtuellen Systemadressen zuordnen muss. Die Systemunterstützung für NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS ist in Windows XP und höheren Versionen verfügbar.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Wird durch einen CoNDIS-Miniporttreiber festgelegt, der keine TAPI-Dienste bereitstellt. Das Festlegen NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO verhindert, dass NDIS den Miniporttreiber an den NDIS TAPI-Proxytreiber (NDPROXY) bindet. Standardmäßig bindet NDIS NDPROXY an alle CoNDIS-Miniporttreiber.

[in, optional] AdapterType

Gibt den E/A-Busschnittstellentyp der NIC des Aufrufers an, wobei es sich in der Regel um den Typ des E/A-Busses handelt, mit dem die NIC verbunden ist, wie folgt:

  • NdisInterfaceInternal
    Gibt eine hostspezifische interne Schnittstelle an.

  • NdisInterfaceIsa
    Gibt die ISA-Schnittstelle an.

  • NdisInterfaceeisa
    Gibt die erweiterte ISA-Schnittstelle (EISA) an.

  • NdisInterfaceMca
    Dies bezieht sich auf den MCA-Bus, der nicht mehr unterstützt wird.

  • NdisInterfaceTurboChannel
    Gibt die Turbo Channel-Schnittstelle an.

  • NdisInterfacePci
    Gibt die PCI-Schnittstelle (Peripheral Component Interconnect) an.

  • NdisInterfacePcMcia
    Gibt die Pc Card-Schnittstelle (Personal Computer Memory Card International Association) an.

Dieser Parameter ist für Zwischentreiber irrelevant, die null für dieses Argument an NdisMSetAttributesEx übergeben sollten.

Rückgabewert

Keine

Bemerkungen

Eine MiniportInitialize-Funktion muss NdisMSetAttributesEx(oder NdisMSetAttributes) aufrufen, bevor eine andere NdisMRegisterXxx - oder NdisXxx-Funktion aufgerufen wird, die von den für NdisMSetAttributesEx bereitgestellten Informationen abhängt. Beispielsweise schlägt der Aufruf von NdisMAllocateMapRegisters eines NIC-Treibers fehl, wenn MiniportInitializenoch nicht NdisMSetAttributesEx aufgerufen hat, wobei attributeFlags mit NDIS_ATTRIBUTE_BUS_MASTER festgelegt ist.

Zwischentreiber müssen NdisMSetAttributesEx anstelle von NdisMSetAttributes aufrufen, und sie müssen NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER in den AttributeFlags festlegen. Das Festlegen dieses Flags bewirkt, dass NDIS einen Zwischentreiber als Vollduplex-Miniporttreiber behandelt, was verhindert, dass seltene, aber zeitweilige Deadlocks im zwischengeschalteten Treiber auftreten. Folglich muss jeder Zwischentreiber in der Lage sein, gleichzeitige Senden und Anzeigen zu verarbeiten.

Deserialisierte Treiber müssen auch NdisMSetAttributesEx aufrufen und NDIS_ATTRIBUTE_DESERIALIZE in den AttributeFlags festlegen. NDIS verwaltet weder eine Sendepaketwarteschlange für einen deserialisierten Treiber noch serialisiert NDIS Aufrufe der MiniportXxx-Funktionen eines solchen Treibers. Ein deserialisierter Treiber macht sich für Folgendes verantwortlich:

  • Annehmen aller eingehenden Sendeanforderungen
  • Internes Anstehen eingehender Sendepakete bei Bedarf, z. B. wenn ein deserialisierter NIC-Treiber derzeit über ausreichende Ressourcen verfügt, um ein eingehendes Sendepaket sofort zu übertragen.
  • Synchronisieren des Zugriffs auf die internen Warteschlangen nach Bedarf für die Routinen des Treibers
  • Abschließen aller angeforderten Senden asynchron durch anschließendes Aufrufen von NdisMSendComplete mit jedem vom Protokoll bereitgestellten Paketdeskriptor, der an seine Miniport(Co)Send(Packets) -Funktion übergeben wird

NDIS geht davon aus, dass alle verbindungsorientierten Miniports deserialisierte Treiber sind, unabhängig von den AttributeFlags , die sie an NdisMSetAttributesEx übergeben. Das heißt, jeder Treiber, der NdisMRegisterMiniport mit 0x05 als MajorNdisVersion aufruft, muss ein deserialisierter Miniporttreiber sein.

Serialisierte NIC-Treiber können eine dieser Funktionen von MiniportInitialize aufrufen, aber NdisMSetAttributes erlaubt dem Aufrufer nicht, das Intervall anzupassen, in dem die MiniportCheckForHang - und/oder MiniportReset-Funktionen eines NIC-Treibers aufgerufen werden.

Der Wert von CheckForHangTimeInSeconds bestimmt das Timeoutintervall der NDIS-Bibliothek bei Gesendeten (falls vorhanden) und anforderungen, die sie in der Warteschlange an den Aufrufer enthält. Standardmäßig wird von NDIS das Zeitüberschreitungsintervall für Warteschlangen (nur für serialisierte Treiber) und Anforderungen im doppelten Intervall der Überprüfung auf Hängen festgelegt. Danach ruft sie die MiniportReset-Funktion auf, es sei denn, der Treiber legt AttributeFlags mit NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT und NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT fest, wenn er NdisMSetAttributesEx aufruft. Zwischentreiber sollten diese Flags beim Aufrufen von NdisMSetAttributesEx festlegen, da ein solcher Treiber nicht bestimmen oder steuern kann, wann der zugrunde liegende NIC-Treiber Senden und Anforderungen verarbeitet.

NIC-Treiber sollten die NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT- und NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT-Flags nicht festlegen, obwohl NDIS eine solche Spezifikation durch einen serialisierten NIC-Treiber berücksichtigt. NIC-Treiber können jedoch das Timeoutintervall anpassen, in dem ihre MiniportReset-Funktionen aufgerufen werden, indem sie eine explizite CheckForHangTimeInSeconds angeben. Beispielsweise kann ein NIC-Treiber, der Ethernet über ein Modem emuliert, nicht jedes Paket innerhalb des Standardtimeoutintervalls der NDIS-Bibliothek abschließen. Wenn ein Paket für eine solche NIC ein Timeout zu haben schien, ging NDIS davon aus, dass die NIC nicht mehr ordnungsgemäß funktionierte, und ruft die MiniportReset-Funktion des Treibers auf. Für den Treiber einer solchen NIC verhindert der Aufruf von NdisMSetAttributesEx mit einem CheckForHangTimeInSeconds , der auf etwas größer als zwei festgelegt ist, unnötige Zurücksetzungen und erweitert das Intervall, in dem die MiniportCheckForHang-Funktion aufgerufen wird, falls vorhanden, zum Testen des Betriebszustands der NIC.

Ein Zwischentreiber muss das NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND-Flag festlegen. Durch das Festlegen dieses Flags wird verhindert, dass NDIS den Treiber anhält, bevor das System in einen Energiesparmodus wechselt.

Ein Legacy-Miniporttreiber, der eine nicht PnP-fähige NIC verwaltet, kann das NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND-Flag festlegen, um zu verhindern, dass NDIS den Treiber anhält, bevor das System in einen Energiesparzustand wechselt. Wenn der Miniporttreiber dieses Flag festlegt, fragt NDIS den Miniporttreiber mit OID_PNP_CAPABILITIES ab, obwohl der Bustreiber für die NIC des Miniporttreibers möglicherweise angegeben hat, dass die NIC nicht PM-fähig ist. Der Miniporttreiber muss der OID_PNP_CAPABILITIES-Anforderung mit NDIS_STATUS_SUCCESS erfolgreich sein. In der NDIS_PM_WAKE_UP_CAPABILITIES Struktur, die von dieser OID zurückgegeben wird, muss der Miniporttreiber auch den Geräteleistungszustand NdisDeviceStateUnspecified für jede Aktivierungsfunktion angeben. Wenn das System in einen Low-Power-Zustand wechselt, ruft NDIS die MiniportHalt-Funktion des Miniporttreibers nicht auf. Bevor das System in einen Zustand mit niedrigerEr Energie übergehen kann, muss der Miniporttreiber alle Hardwarekontexte speichern, die er verwaltet. Wenn eine OID_PNP_SET_POWER Anforderung an den D3-Zustand empfangen wird, muss der Miniporttreiber seine NIC auf den entsprechenden Zustand für den Low-Power-Zustand festlegen. Beim Empfang einer OID_PNP_SET_POWER Anforderung an den D0-Zustand muss der Miniporttreiber seine NIC auf den entsprechenden Zustand für den Betriebszustand festlegen.

Ein Miniporttreiber, der die überraschende Entfernung seines Geräts unterstützt (Entfernung ohne Benachrichtigung über die Benutzeroberfläche), muss NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK festlegen. Dadurch ruft NDIS die MiniportPnPEventNotify-Funktion des Treibers auf, wobei PnPEvent auf NdisDevicePnPEventSurpriseRemoved festgelegt ist, wenn das Gerät des Miniports ohne Benachrichtigung entfernt wird. Darüber hinaus unterdrückt das Festlegen NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK die Anzeige eines Warnungsdialogfelds, in dem der Benutzer aufgefordert wird, das Gerät vor dem Entfernen zu beenden.

Ein Miniporttreiber, der sowohl verbindungslose als auch verbindungsorientierte Geräte unterstützen kann, muss NDIS_ATTRIBUTE_NOT_CO_NDIS festlegen, wenn sein Gerät ein verbindungsloses Gerät ist. Andernfalls geht NDIS irrig davon aus, dass sein Gerät verbindungsorientiert ist, da der Treiber verbindungsorientierte Miniporttreiberfunktionen bei NdisMRegisterMiniport registriert.

Im Allgemeinen muss ein NIC-Treiber NdisMSetAttributesEx aufrufen, bevor er eine NdisXxx-Funktion aufruft, die Hardwareressourcen in der Registrierung für seine NIC beansprucht, da NDIS den AttributeFlags-Wert aufweisen muss, bevor ein solcher Aufruf erfolgt, und weil der Treiber normalerweise den Arbeitsspeicher bei MiniportAdapterContext benötigt, um Informationen für diese Aufrufe zu speichern. Diese Einschränkung impliziert, dass die MiniportInitialize-Funktion eines NIC-Treibers nicht die folgende NdisXxx aufrufen kann, bevor NdisMSetAttributesEx aufgerufen wird:

Vor dem Aufruf von NdisMSetAttributesEx kann die MiniportInitialize-Funktion eines Treibers jedoch die Ndis. aufrufen. Konfigurationsfunktionen zum Abrufen der in der Registrierung installierten Konfigurationsinformationen. MiniportInitialize kann auch die bustypspezifischen NdisReadXxx-Funktionen aufrufen, z. B. NdisReadPciSlotInformation, solange der installierte Registrierungseintrag für den Schnittstellentyp des Treibers mit den bustypspezifischen NdisReadXxxMiniportInitialize-Aufrufen übereinstimmt.

Das für NdisMSetAttributesEx bereitgestellte MiniportAdapterContext-Handle wird zu einem Eingabeparameter für alle MiniportXxx-Funktionen, die zusammen mit MiniportInitialize im Aufruf von NdisMRegisterMiniport oder NdisIMRegisterLayeredMiniport registriert wurden. In der Regel handelt es sich bei diesem Handle um einen Zeiger auf den von MiniportInitialize zugeordneten Speicher, in dem der Treiber den NIC-spezifischen Laufzeitzustand beibehält.

Anforderungen

Anforderung Wert
Header ndis.h (include Ndis.h)
Bibliothek Ndis.lib
IRQL PASSIVE_LEVEL

Weitere Informationen