PROTOCOL_NET_PNP_EVENT Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die ProtocolNetPnPEvent-Funktion auf, um ein Netzwerk Plug & Play Ereignis, ein NDIS-PnP-Ereignis oder ein Energieverwaltungsereignis für einen Protokolltreiber anzugeben.

Hinweis Sie müssen die Funktion mit dem typ PROTOCOL_NET_PNP_EVENT deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

Parameter

[in] ProtocolBindingContext

Das Handle für einen vom Protokolltreiber zugeordneten Kontextbereich, in dem dieser Treiber Laufzeitstatusinformationen pro Bindung verwaltet. Der Protokolltreiber hat dieses Handle bereitgestellt, als er die NdisOpenAdapterEx-Funktion aufgerufen hat. Ein NetEventXxx-Ereignis , das mit einem NULLProtocolBindingContext angegeben wird, gilt für alle Bindungen. NetEventBindList und NetEventBindsComplete werden immer mit nullProtocolBindingContext angegeben. NetEventReconfigure kann mit einem angegebenen ProtocolBindingContext oder mit einem NULLProtocolBindingContext angegeben werden.

[in] NetPnPEventNotification

Ein Zeiger auf eine NET_PNP_EVENT_NOTIFICATION Struktur, die das Plug & Play Ereignis oder Power Management-Ereignis beschreibt, das NDIS für den Protokolltreiber angibt.

Rückgabewert

ProtocolNetPnPEvent kann folgendes zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Protokolltreiber hat das angegebene Netzwerk Plug & Play ereignis, das NDIS-PnP-Ereignis oder das Energieverwaltungsereignis erfolgreich verarbeitet. Die Bedeutung dieses status Code hängt vom NetEvent-Code im gepufferten ab. NET_PNP_EVENT_NOTIFICATION Struktur bei NetPnPEvent: NetEventSetPower Der Protokolltreiber hat alle treiberspezifischen Aktionen ausgeführt, die erforderlich sind, um den Übergang des Geräts in den angeforderten Gerätestromzustand vorzubereiten. NetEventQueryPower Der zugrunde liegende Adapter kann in den angeforderten Gerätestromzustand übergehen. NetEventQueryRemoveDevice Der zugrunde liegende Adapter kann entfernt werden. NetEventCancelRemoveDevice Der Protokolltreiber hat alle treiberspezifischen Aktionen ausgeführt, die erforderlich sind, um die abgebrochene Entfernung des zugrunde liegenden Adapters vorzubereiten. NetEventReconfigure Der Protokolltreiber hat die geänderte Konfiguration akzeptiert. NetEventBindList Der Protokolltreiber verfügt über die neue Bindungsliste und hat die zugehörige Verarbeitung ausgeführt. NetEventBindsComplete Der Protokolltreiber hat den Hinweis von NDIS bestätigt, dass der Protokolltreiber an alle verfügbaren zugrunde liegenden Adapter gebunden ist. NetEventPnPCapabilities Der Protokolltreiber hat bestätigt, dass er die aktuellen Aktivierungsfunktionen des zugrunde liegenden Adapters empfangen hat, der der angegebenen Bindung zugeordnet ist. NetEventPause Die angegebene Protokollbindung wurde in den Zustand Angehalten versetzt. Die Bindung wechselt in den Status Angehalten , nachdem NDIS alle ausstehenden Sendeanforderungen für die Bindung abgeschlossen hat. Weitere Informationen zu Pausenvorgängen finden Sie unter Anhalten einer Bindung. NetEventRestart Die angegebene Protokollbindung hat den Status Neustarten erreicht. Nachdem der Protokolltreiber bereit ist, Sende- und Empfangsvorgänge für die Bindung fortzusetzen, wechselt die Bindung in den Status Wird ausgeführt . NetEventPortActivation Der Protokolltreiber hat die Aktivierung eines Ports bestätigt, der der angegebenen Bindung zugeordnet ist. Weitere Informationen zur Portaktivierung finden Sie unter Aktivieren eines NDIS-Ports. NetEventPortDeactivation Der Protokolltreiber hat die Aktivierung eines Ports bestätigt, der der angegebenen Bindung zugeordnet ist.
NDIS_STATUS_PENDING	Der Protokolltreiber gibt seine Antwort auf das angegebene Ereignis asynchron mit einem Aufruf von zurück. NdisCompleteNetPnPEvent-Funktion .
NDIS_STATUS_RESOURCES	Der Protokolltreiber konnte nicht die erforderlichen Systemressourcen abrufen, um das angegebene Plug & Play- oder Energieverwaltungsereignis zu erfüllen.
NDIS_STATUS_NOT_SUPPORTED	Protokolltreiber von NDIS 6.0 und höher dürfen diese status nicht zurückgeben. Ein NDIS 5. Der x-Protokolltreiber, der Plug & Play nicht unterstützt, kann diese status als Reaktion auf eine NetEventSetPower zurückgeben, um anzugeben, dass NDIS die Bindung an den zugrunde liegenden Adapter aufheben soll.
NDIS_STATUS_FAILURE	Der Protokolltreiber hat das angegebene Ereignis aus anderen als den in der vorherigen Liste aufgeführten Gründen nicht bestanden.

Bei einem Protokolltreiber können die Ereignisse NetEventQueryRemoveDevice und NetEventPortActivation fehlschlagen.

Wenn ein Protokolltreiber beim NetEventPortActivation-Ereignis fehlschlägt, sollte er in nachfolgenden Vorgängen keine zugeordneten Ports verwenden.

Ein Protokolltreiber sollte immer die Ereignisse NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation und NetEventPnPCapabilities ausführen, indem NDIS_STATUS_SUCCESS zurückgegeben wird.

Hinweise

Die ProtocolNetPnPEvent-Funktion ist in Protokolltreibern erforderlich, um Plug & Play und Energieverwaltung zu unterstützen. NDIS ruft ProtocolNetPnPEvent auf, um einen Protokolltreiber zu benachrichtigen, dass ein Netzwerk Plug & Play Ereignis, ein NDIS-PnP-Ereignis oder ein Power Management-Ereignis aufgetreten ist.

The NET_PNP_EVENT_NOTIFICATION Struktur, die an ProtocolNetPnPEvent übergeben wird, beschreibt das Ereignis. ProtocolNetPnPEvent interpretiert zwei grundlegende Informationen in der NET_PNP_EVENT_NOTIFICATION-Struktur:

Ein Code im NetEvent-Member, der den Typ des Plug & Play- oder Power Management-Ereignisses identifiziert.
Ereignisspezifische Informationen. Bei einem NetEventSetPower-Ereignis enthält das Buffer-Element beispielsweise den Energiezustand des Geräts, in den das Gerät übergehen wird.

Der Protokolltreiber sollte den NetPnPEvent-Zeiger speichern. Dieser Zeiger ist ein erforderlicher Eingabeparameter für die NdisCompleteNetPnPEvent-Funktion , die der Protokolltreiber anschließend aufrufen muss, wenn ProtocolNetPnPEvent NDIS_STATUS_PENDING zurückgibt.

Ein Protokolltreiber sollte immer auf ein NetEventQueryPower-Ereignis erfolgreich sein. Nach dem Herstellen einer aktiven Verbindung kann ein Protokolltreiber die PoRegisterSystemState-Funktion aufrufen, um einen fortlaufend ausgelasteten Zustand zu registrieren. Solange die Statusregistrierung aktiv ist, versucht der Power Manager nicht, das System in den Standbymodus zu versetzen. Nachdem die Verbindung inaktiv wurde, bricht der Protokolltreiber die Zustandsregistrierung ab, indem er die Funktion PoUnregisterSystemState aufruft . Ein Protokolltreiber sollte niemals versuchen, zu verhindern, dass das System in den Ruhezustand wechselt, indem ein NetEventQueryPower-Ereignis fehlschlägt. Beachten Sie, dass auf ein NetEventQueryPower-Ereignis immer ein NetEventSetPower-Ereignis folgt. Ein NetEventSetPower-Ereignis , das den aktuellen Energiezustand des zugrunde liegenden Geräts angibt, bricht das NetEventQueryPower-Ereignis ab.

Wenn ein Protokolltreiber ein Gerät nicht freigeben kann (z. B. weil das Gerät verwendet wird), muss ein NetEventQueryRemoveDevice-Ereignis fehlschlagen, indem NDIS_STATUS_FAILURE zurückgegeben wird.

Ein Protokolltreiber sollte immer eine NetEventCancelRemoveDevice, eine NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause oder NetEventPortDeactivation ausführen, indem NDIS_STATUS_SUCCESS zurückgegeben wird.

Bei der Behandlung einer NetEventReconfigure oder einer NetEventBindList sollte ein Protokolltreiber die dem Ereignis zugeordneten Daten überprüfen. Weitere Informationen zu diesen Daten finden Sie unter NET_PNP_EVENT_NOTIFICATION.

NDIS ruft ProtocolNetPnPEvent unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine ProtocolNetPnPEvent-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der funktion identifiziert, die Sie definieren. Windows bietet eine Reihe von Funktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Funktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine ProtocolNetPnPEvent-Funktion mit dem Namen "MyNetPnPEvent" zu definieren, verwenden Sie den typ PROTOCOL_NET_PNP_EVENT , wie in diesem Codebeispiel gezeigt:

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

Der PROTOCOL_NET_PNP_EVENT Funktionstyp ist in der Ndis.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den PROTOCOL_NET_PNP_EVENT Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für NDIS-Treiber.

Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL