PROTOCOL_NET_PNP_EVENT Rückruffunktion (ndis.h)
NDIS ruft die ProtocolNetPnPEvent--Funktion auf, um ein Netzwerk-Plug-and-Play-Ereignis, ein NDIS PnP-Ereignis oder ein Energieverwaltungsereignis an einen Protokolltreiber anzugeben.
Syntax
PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;
NDIS_STATUS ProtocolNetPnpEvent(
[in] NDIS_HANDLE ProtocolBindingContext,
[in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}
Parameter
[in] ProtocolBindingContext
Das Handle zu einem vom Protokolltreiber zugewiesenen Kontextbereich, in dem dieser Treiber pro Bindung Laufzeitstatusinformationen verwaltet. Der Protokolltreiber hat dieses Handle beim Aufrufen der NdisOpenAdapterEx--Funktion bereitgestellt. Ein NetEventXxx--Ereignis, das mit einem NULL-ProtocolBindingContext- für alle Bindungen angegeben ist. NetEventBindList und NetEventBindsComplete- werden immer mit einem NULL-ProtocolBindingContext-angegeben. NetEventReconfigure- kann mit einem angegebenen ProtocolBindingContext- oder mit einem NULLProtocolBindingContext-angegeben werden.
[in] NetPnPEventNotification
Ein Zeiger auf ein NET_PNP_EVENT_NOTIFICATION Struktur, die das Plug and Play-Ereignis oder das Power Management-Ereignis beschreibt, das NDIS für den Protokolltreiber angibt.
Rückgabewert
ProtocolNetPnPEvent- kann eine der folgenden Werte zurückgeben:
| Rückgabecode | Beschreibung |
|---|---|
|
Der Protokolltreiber hat das angegebene Netzwerk-Plug-and-Play-Ereignis, das NDIS-PnP-Ereignis oder das Energieverwaltungsereignis erfolgreich behandelt. Die Bedeutung dieses Statuscodes hängt vom NetEvent- Code im pufferierten Code ab.
NET_PNP_EVENT_NOTIFICATION Struktur bei NetPnPEvent:
|
|
Der Protokolltreiber gibt seine Antwort auf das angegebene Ereignis asynchron mit einem Aufruf des NdisCompleteNetPnPEvent-Funktion. |
|
Der Protokolltreiber konnte die erforderlichen Systemressourcen nicht abrufen, um das angegebene Plug and Play- oder Power Management-Ereignis zu erfüllen. |
|
NDIS 6.0 und höhere Protokolltreiber dürfen diesen Status nicht zurückgeben. Ein NDIS 5.x Protokolltreiber, der Plug and Play nicht unterstützt, kann diesen Status als Reaktion auf eine NetEventSetPower- zurückgeben, um anzugeben, dass NDIS sie vom zugrunde liegenden Adapter aufheben soll. |
|
Der Protokolltreiber hat das angegebene Ereignis aus anderen Gründen als den in der vorherigen Liste angegebenen nicht bestanden. |
Ein Protokolltreiber kann die NetEventQueryRemoveDevice- und NetEventPortActivation--Ereignisse fehlschlagen.
Wenn ein Protokolltreiber das NetEventPortActivation--Ereignis fehlschlägt, sollte er keine zugeordneten Ports in nachfolgenden Vorgängen verwenden.
Ein Protokolltreiber sollte immer den NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventCancelReviceEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation, und NetEventPnPCapabilities Ereignisse durch Zurückgeben von NDIS_STATUS_SUCCESS.
Bemerkungen
Die ProtocolNetPnPEvent- Funktion ist in Protokolltreibern erforderlich, um Plug-and-Play- und Power Management zu unterstützen. NDIS ruft ProtocolNetPnPEvent- auf, um einen Protokolltreiber zu benachrichtigen, dass ein Netzwerk-Plug-and-Play-Ereignis, ein NDIS PnP-Ereignis oder ein Power Management-Ereignis aufgetreten ist.
Das 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-and Play- oder Power Management-Ereignisses identifiziert.
- Ereignisspezifische Informationen. Mit einem NetEventSetPower- Ereignis enthält beispielsweise das Buffer Member den Gerätestromzustand, zu dem das Gerät wechselt.
Ein Protokolltreiber sollte immer 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 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 die funktion PoUnregisterSystemState aufgerufen wird. 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 einen NetEventCancelRemoveDevice, ein NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPauseoder NetEventPortDeactivation durch Zurückgeben von NDIS_STATUS_SUCCESS.
Bei der Behandlung eines NetEventReconfigure oder eines 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- bei IRQL = PASSIVE_LEVEL auf.
beispiele für
Um eine ProtocolNetPnPEvent--Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Funktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Funktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.Um beispielsweise eine ProtocolNetPnPEvent--Funktion zu definieren, die den Namen "MyNetPnPEvent" hat, verwenden Sie den PROTOCOL_NET_PNP_EVENT Typ, 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 wird in der Ndis.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den funktionstyp PROTOCOL_NET_PNP_EVENT in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Unterstützt in NDIS 6.0 und höher. |
| Zielplattform- | Fenster |
| Header- | ndis.h (include Ndis.h) |
| IRQL- | PASSIVE_LEVEL |