PROTOCOL_NET_PNP_EVENT Rückruffunktion (ndis.h)

NDIS ruft die ProtocolNetPnPEvent-Funktion auf, um ein Netzwerk Plug & Play Ereignis, ein NDIS PnP-Ereignis oder ein Power Management-Ereignis an einen Protokolltreiber anzugeben.

Hinweis Sie müssen die Funktion mithilfe des PROTOCOL_NET_PNP_EVENT Typs 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

Der Handle zu einem Protokolltreiber zugeordneten Kontextbereich, in dem dieser Treiber pro Bindungsstatusinformationen verwaltet. Der Protokolltreiber hat diesen Handle beim Aufrufen der Funktion "NdisOpenAdapterEx " bereitgestellt. Ein NetEventXxx-Ereignis , das mit einem NULLProtocolBindingContext angegeben ist, gilt für alle Bindungen. NetEventBindList und NetEventBindsComplete werden immer mit einem 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 das Power Management-Ereignis beschreibt, das NDIS angibt, dem Protokolltreiber.

Rückgabewert

ProtocolNetPnPEvent kann eine der folgenden Elemente zurückgeben:

Rückgabecode Beschreibung
NDIS_STATUS_SUCCESS
Der Protokolltreiber behandelt das angegebene Netzwerk Plug & Play Ereignis, NDIS PnP-Ereignis oder Power Management-Ereignis erfolgreich. Die Bedeutung dieses Statuscodes hängt vom NetEvent-Code im Puffer ab. NET_PNP_EVENT_NOTIFICATION Struktur bei NetPnPEvent:
NetEventSetPower
Der Protokolltreiber hat alle treiberspezifischen Aktionen ausgeführt, die für den Übergang des Geräts zum angeforderten Gerätestromzustand erforderlich sind.
NetEventQueryPower
Der zugrunde liegende Adapter kann auf den angeforderten Gerätestromzustand übersteigen.
NetEventQueryRemoveDevice
Der zugrunde liegende Adapter kann entfernt werden.
NetEventCancelRemoveDevice
Der Protokolltreiber hat alle treiberspezifischen Aktionen ausgeführt, die zum Vorbereiten der abgebrochenen Entfernung des zugrunde liegenden Adapters erforderlich sind.
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 die Angabe 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 Reaktivierungsfunktionen des zugrunde liegenden Adapters erhalten hat, der der angegebenen Bindung zugeordnet ist.
NetEventPause
Die angegebene Protokollbindung hat den Status " Anhalten " eingegeben. Die Bindung wird den Angehaltenen Zustand eingeben, nachdem NDIS alle ausstehenden Sendenanforderungen für die Bindung abgeschlossen hat. Weitere Informationen zu Pausenvorgängen finden Sie unter Anhalten einer Bindung.
NetEventRestart
Die angegebene Protokollbindung hat den Neustartstatus eingegeben. Nachdem der Protokolltreiber bereit ist, sende- und empfangene Vorgänge für die Bindung fortzusetzen, gibt die Bindung den Status "Ausführen " ein.
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-Portes.
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 an das angegebene Ereignis zurück. NdisCompleteNetPnPEvent-Funktion .
NDIS_STATUS_RESOURCES
Der Protokolltreiber konnte die erforderlichen Systemressourcen nicht abrufen, um das angegebene Plug & Play- oder Power Management-Ereignis zu erfüllen.
NDIS_STATUS_NOT_SUPPORTED
NDIS 6.0 und spätere Protokolltreiber dürfen diesen Status nicht zurückgeben. Ein NDIS 5. x-Protokolltreiber, der Plug & Play nicht unterstützt, kann diesen Status als Reaktion auf eine NetEventSetPower zurückgeben, um anzugeben, dass NDIS sie vom zugrunde liegenden Adapter aufheben sollte.
NDIS_STATUS_FAILURE
Der Protokolltreiber hat das angegebene Ereignis aus anderen Gründen als die in der vorherigen Liste aufgeführten Ereignisse fehlgeschlagen.
 

Ein Protokolltreiber kann das NetEventQueryRemoveDevice - und NetEventPortActivation-Ereignis 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, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation und NetEventPnPCapabilities-Ereignisse zurückgeben, indem NDIS_STATUS_SUCCESS zurückgegeben werden.

Bemerkungen

Die ProtocolNetPnPEvent-Funktion ist in Protokolltreibern erforderlich, um Plug & Play und Power Management 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.

Für 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. Mit einem NetEventSetPower-Ereignisenthält das Puffermitglied z. B. den Gerätestromstatus, zu dem das Gerät übergibt.
Der Protokolltreiber sollte den NetPnPEvent-Zeiger speichern. Dieser Zeiger ist ein erforderlicher Eingabeparameter für die NdisCompleteNetPEvent-Funktion , die der Protokolltreiber anschließend aufrufen muss, wenn ProtocolNetPnPEvent NDIS_STATUS_PENDING zurückgibt.

Ein Protokolltreiber sollte immer ein NetEventQueryPower-Ereignis erfolgreich sein. Nach dem Einrichten einer aktiven Verbindung kann ein Protokolltreiber die PoRegisterSystemState-Funktion aufrufen, um einen kontinuierlich gebuchten Zustand zu registrieren. Solange die Staatliche Registrierung wirksam ist, versucht der Power Manager nicht, das System in den Schlaf zu setzen. Nachdem die Verbindung inaktiv wird, wird der Protokolltreiber die Statusregistrierung durch Aufrufen der Funktion "PoUnregisterSystemState " abgebrochen. Ein Protokolltreiber sollte niemals versuchen, das System daran zu hindern, den Schlafzustand zu wechseln, indem ein NetEventQueryPower-Ereignis fehlschlägt. Beachten Sie, dass ein NetEventQueryPower-Ereignis immer von einem NetEventSetPower-Ereignis gefolgt wird. Ein NetEventSetPower-Ereignis , das den aktuellen Leistungszustand 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 es ein NetEventQueryRemoveDevice-Ereignis fehlschlagen, indem NDIS_STATUS_FAILURE zurückgegeben wird.

Ein Protokolltreiber sollte immer einen 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 daten überprüfen, die dem Ereignis zugeordnet sind. Weitere Informationen zu diesen Daten finden Sie unter NET_PNP_EVENT_NOTIFICATION.

NDIS ruft ProtocolNetPnPEvent bei IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine ProtocolNetPnPEvent-Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Funktion identifiziert, die Sie definieren. Windows bietet einen Satz von Funktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Funktionstypen hilft bei der Codeanalyse für Treiber, statischer Treiberüberprüfung (SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine ProtocolNetPnPEvent-Funktion zu definieren, die "MyNetPnPEvent " genannt wird, 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 Kopfzeilendatei Ndis.h definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie die Use_decl_annotations Anmerkungen zu Ihrer Funktionsdefinition hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den PROTOCOL_NET_PNP_EVENT Funktionstyp in der Kopfzeilendatei angewendet werden, 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 Annotating Function Behavior.

Anforderungen

   
Unterstützte Mindestversion (Client) Unterstützt in NDIS 6.0 und höher.
Zielplattform Windows
Kopfzeile ndis.h (einschließlich Ndis.h)
IRQL PASSIVE_LEVEL

Weitere Informationen

NET_PNP_EVENT_NOTIFICATION

NdisCompleteNetPnPEvent

NdisOpenAdapterEx

PoRegisterSystemState

PoUnregisterSystemState