Behandeln von PnP-Ereignissen und Energieverwaltungsereignissen in einem Protokolltreiber

Wenn das Betriebssystem ein Plug & Play(PnP)-E/A-Anforderungspaket (IRP) oder ein Energieverwaltungs-IRP an ein Zielgerätobjekt ausgibt, das eine Netzwerkschnittstelle Karte (NIC) darstellt, fängt NDIS den IRP ab. NDIS gibt das Ereignis für jeden gebundenen Protokolltreiber und jeden gebundenen Zwischentreiber an, indem die ProtocolNetPnPEvent-Funktion des Treibers aufgerufen wird. Beim Aufruf von ProtocolNetPnPEvent übergibt NDIS einen Zeiger an eine NET_PNP_EVENT_NOTIFICATION , die eine NET_PNP_EVENT-Struktur enthält. Die NET_PNP_EVENT-Struktur beschreibt das PnP-Ereignis oder das Energieverwaltungsereignis, das angegeben wird. Weitere Informationen zur PnP-Schnittstelle des Protokolltreibers finden Sie unter Behandeln von PnP-Ereignisbenachrichtigungen in einem Protokolltreiber.

Die folgende Liste enthält PnP- und Energieverwaltungsereignisse, wie im NetEvent-Code in der NET_PNP_EVENT-Struktur angegeben:

• NetEventSetPower

  Gibt eine Set Power Request an, die angibt, dass der Miniportadapter in einen bestimmten Energiezustand übergehen soll. Ein energieverwaltungsfähiger Protokolltreiber sollte dieses Ereignis immer erfolgreich ausführen, indem er NDIS_STATUS_SUCCESS zurückgibt. Ein alter Protokolltreiber kann NDIS_STATUS_NOT_SUPPORTED zurückgeben, um anzugeben, dass NDIS die Bindung vom Miniportadapter aufheben soll.

  Nach dem Ausgeben der Set-Energieanforderung hält NDIS den Treiberstapel an, wenn der Miniportadapter in einen Energiesparzustand überwechselt. NDIS startet den Treiberstapel vor der Set-Power-Anforderung neu, wenn der Miniportadapter in den Arbeitszustand (D0) wechselt. Weitere Informationen zum Anhalten und Neustarten des Treiberstapels finden Sie unter Anhalten eines Treiberstapels.

  Wenn sich der Miniportadapter in einem Energiesparzustand befindet, kann der Protokolltreiber keine OID-Anforderungen ausstellen. Diese Anforderung ist eine zusätzliche Energieverwaltungseinschränkung, die den anderen Einschränkungen hinzugefügt wird, die gelten, wenn sich der Treiberstapel im Zustand Angehalten befindet.

  Wenn der zugrunde liegende Miniportadapter nicht energieverwaltungsfähig ist, legt der Miniporttreiber den PowerManagementCapabilities-Member von NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES auf NULL fest, und NDIS legt den PowerManagementCapabilities-Member von NDIS_BIND_PARAMETERS auf NULL fest.

  Hinweis Ab NDIS 6.30 muss der Protokolltreiber nach der Benachrichtigung über dieses Ereignis die Generierung neuer E/A-Anforderungen beenden und sollte nicht auf den Abschluss ausstehender E/A-Anforderungen im Kontext des Aufrufs von ProtocolNetPnPEvent warten.

  Weitere Informationen zu Set-Power-Ereignissen finden Sie unter Behandeln von PnP-Ereignissen und Energieverwaltungsereignissen in einem Zwischentreiber.

• NetEventQueryPower

  Gibt eine Abfrageleistungsanforderung an, die abfragt, ob der zugrunde liegende Miniportadapter einen Übergang zu einem bestimmten Energiezustand vornehmen kann. Ein Protokolltreiber sollte immer eine NetEventQueryPower ausführen. Nach dem Herstellen einer aktiven Verbindung kann ein Protokolltreiber PoRegisterSystemState aufrufen, um einen kontinuierlichen Auslastungsstatus zu registrieren. Solange die Statusregistrierung wirksam ist, versucht der Power Manager nicht, das System in den Ruhezustand zu versetzen. Nachdem die Verbindung inaktiv wurde, bricht der Protokolltreiber die Statusregistrierung ab, indem er PoUnregisterSystemState aufruft. Ein Protokolltreiber sollte niemals versuchen, zu verhindern, dass das System in den Ruhezustand wechselt, indem ein NetEventQueryRemoveDevice fehlschlägt. Beachten Sie, dass einer NetEventQueryPower immer ein NetEventSetPower folgt. Ein NetEventSetPower , der den aktuellen Energiezustand des Geräts festlegt, bricht netEventQueryPower auf.

  Hinweis Ab NDIS 6.30 sollte der Protokolltreiber nach einer Benachrichtigung über dieses Ereignis nicht auf den Abschluss ausstehender E/A-Anforderungen im Kontext des Aufrufs von ProtocolNetPnPEvent warten.

• NetEventQueryRemoveDevice

  Gibt eine Abfrage entfernen Device-Anforderung an, die abfragt, ob die NIC entfernt werden kann, ohne Vorgänge zu unterbrechen. Wenn ein Protokolltreiber ein Gerät nicht freigeben kann (z. B. weil das Gerät verwendet wird), muss ein NetEventQueryRemoveDevice fehlschlagen, indem NDIS_STATUS_FAILURE zurückgegeben wird.

• NetEventCancelRemoveDevice

  Gibt eine Anforderung "Gerät abbrechen entfernen" an, die das Entfernen einer zugrunde liegenden NIC abbricht. Der Protokolltreiber sollte dieses Ereignis immer erfolgreich ausführen, indem er NDIS_STATUS_SUCCESS zurückgibt.

• NetEventReconfigure

  Gibt an, dass sich die Konfiguration für eine Netzwerkkomponente geändert hat. Wenn ein Benutzer z. B. die IP-Adresse für TCP/IP ändert, gibt NDIS dieses Ereignis dem TCP/IP-Protokoll mit dem NetEventReconfigure-Code an. Der Protokolltreiber kann in seltenen Fällen einen Fehlercode zurückgeben, wenn er die angegebenen Konfigurationsänderungen nicht anwenden kann und keine Standardwerte verfügbar sind. Ein fehlgeschlagener Versuch, Arbeitsspeicher zuzuweisen, ist ein Beispiel für einen Fall, in dem das Protokoll einen Fehlercode zurückgibt. Das Zurückgeben eines Fehlercodes kann dazu führen, dass der Benutzer aufgefordert wird, das System neu zu starten.

  Ein Protokoll sollte NetEventReconfigure-bezogene Daten überprüfen, die an die ProtocolNetPnPEvent-Funktion übergeben werden. Weitere Informationen zu diesen Daten finden Sie unter NET_PNP_EVENT für Protokolltreiber.

• NetEventBindList

  Gibt für einen Protokolltreiber an, dass seine Bindungslistenverarbeitungsreihenfolge neu konfiguriert wurde. Diese Liste gibt eine relative Reihenfolge an, die bei der Verarbeitung auf die Bindungen des Protokolls angewendet werden soll, z. B. eine Benutzeranforderung, die an eine von mehreren Bindungen weitergeleitet werden kann. Der Puffer, der mit diesem Ereignis übergeben wird, enthält eine Liste von Gerätenamen, die als NULL-beendete Unicode-Zeichenfolgen formatiert sind. Das Format jedes Gerätenamens ist identisch mit dem DeviceName-Parameter , der an einen Aufruf von ProtocolBindAdapterEx übergeben wird.

  Ein Protokoll sollte NetEventBindList-bezogene Daten überprüfen, die an die ProtocolNetPnPEvent-Funktion übergeben werden. Weitere Informationen zu diesen Daten finden Sie unter NET_PNP_EVENT für Protokolltreiber.

  Ein Protokoll sollte NetEventBindList-bezogene Daten überprüfen, die an die ProtocolNetPnPEvent-Funktion übergeben werden. Weitere Informationen zu diesen Daten finden Sie unter NET_PNP_EVENT für Protokolltreiber.

• NetEventBindsComplete

  Gibt an, dass ein Protokolltreiber an alle Netzwerkkarten gebunden ist, an die er gebunden werden kann. NDIS gibt keine weiteren Bindungen an den Protokolltreiber an, es sei denn, beispielsweise ist eine PnP-NIC an das System angeschlossen.

• NetEventPnPCapabilities

  Gibt an, dass der Benutzer die Aktivierungsfunktionen des zugrunde liegenden Adapters aktiviert oder deaktiviert hat. (Der ProtocolBindingContext-Parameter , den NDIS an ProtocolNetPnPEvent übergibt, gibt die Bindung an.)

• NetEventPause

  Gibt an, dass die angegebene Protokollbindung in denPausing-Zustand gelangen soll. Die Bindung wird in den Status Angehalten versetzt, nachdem NDIS alle ausstehenden Sendeanforderungen für die Bindung abgeschlossen hat. Weitere Informationen zum Anhalten einer Bindung finden Sie unter Anhalten einer Bindung.

• NetEventRestart

  Gibt an, dass die angegebene Protokollbindung den Status Neustarten erreicht hat. Nachdem der Protokolltreiber bereit ist, Sende- und Empfangsvorgänge für die Bindung fortzusetzen, wechselt die Bindung in den Status Ausführen. Weitere Informationen zum Neustarten einer Bindung finden Sie unter Neustarten einer Bindung.

• NetEventPortActivation

  Gibt die Aktivierung einer Liste von Ports an, die der angegebenen Bindung zugeordnet sind. Weitere Informationen zum Anhalten einer Bindung finden Sie unter Behandeln des PnP-Ereignisses für die Portaktivierung.

• NetEventPortDeactivation

  Gibt die Deaktivierung einer Liste von Ports an, die der angegebenen Bindung zugeordnet sind. Weitere Informationen zum Anhalten einer Bindung finden Sie unter Behandeln des PnP-Ereignisses zur Portdeaktivierung.

• NetEventIMReEnableDevice

  Gibt an, dass die Konfiguration für einen virtuellen Miniport eines NDIS 6.0- oder höher-Zwischentreibers geändert wurde. NetEventIMReEnableDevice ähnelt dem NetEventReconfigure-Ereignis , mit der Ausnahme, dass der Zwischentreiber dieses Ereignis für einen einzelnen virtuellen Miniport empfängt und das NetEventReconfigure-Ereignis für alle virtuellen Miniports des zwischengeschalteten Treibers gilt. Beispielsweise empfängt ein Zwischentreiber das NetEventIMReEnableDevice-Ereignis, wenn ein Benutzer deaktiviert und dann einen einzelnen virtuellen Miniport aus dem Geräte-Manager oder einer anderen Quelle aktiviert. Beispiele für die Energieverwaltung für fortgeschrittene Treiber finden Sie im Beispiel NDIS MUX Intermediate Driver und Notify Object Driver, das im Repository für Windows-Treiberbeispiele auf GitHub verfügbar ist.

Das Pufferelement der NET_PNP_EVENT-Struktur verweist auf einen Puffer, der spezifische Informationen für das angegebene Ereignis enthält.

Ein Protokolltreiber kann den Aufruf von ProtocolNetPnPEvent mit NdisCompleteNetPnPEvent asynchron abschließen.