IoRegisterPlugPlayNotification-Funktion (wdm.h)

Artikel
02/29/2024

Die IoRegisterPlugPlayNotification-Routine registriert eine PnP-Benachrichtigungsrückrufroutine (Plug & Play), die aufgerufen werden soll, wenn ein PnP-Ereignis der angegebenen Kategorie auftritt.

Syntax

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

Parameter

[in] EventCategory

Gibt einen Enumerationswert aus IO_NOTIFICATION_EVENT_CATEGORY an, der die Kategorie des PnP-Ereignisses angibt, für das die Rückrufroutine registriert wird.

[in] EventCategoryFlags

Flagbits, die den Registrierungsvorgang ändern. Mögliche Werte sind:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Nur gültig mit einer EventCategory von EventCategoryDeviceInterfaceChange. Wenn festgelegt, ruft der PnP-Manager die Treiberrückrufroutine für jede Geräteschnittstelle instance auf, die derzeit registriert und aktiv ist, und registriert die Rückrufroutine für zukünftige Ein- oder Entfernungen von Geräteschnittstelleninstanzen.

[in, optional] EventCategoryData

Ein Zeiger auf weitere Informationen zu den Ereignissen, für die CallbackRoutine registriert wird. Die Informationen variieren für verschiedene EventCategory-Werte :

Wenn EventCategoryauf EventCategoryDeviceInterfaceChange festgelegt ist, muss EventCategoryData auf eine GUID verweisen, die eine Geräteschnittstellenklasse angibt. CallbackRoutine wird aufgerufen, wenn eine Schnittstelle dieser Klasse aktiviert oder entfernt wird.
Wenn EventCategoryauf EventCategoryHardwareProfileChange festgelegt ist, muss EventCategoryDataNULL sein.
Wenn EventCategoryden Wert EventCategoryTargetDeviceChange hat, muss EventCategoryData auf das Dateiobjekt verweisen, für das eine PnP-Benachrichtigung angefordert wird.

[in] DriverObject

Ein Zeiger auf das Treiberobjekt des Aufrufers.

Um sicherzustellen, dass der Treiber geladen bleibt, während er für die PnP-Benachrichtigung registriert ist, erhöht dieser Aufruf die Verweisanzahl für DriverObject. Der PnP-Manager verringert die Verweisanzahl, wenn diese Registrierung entfernt wird.

Für EventCategoryTargetDeviceChange darf DriverObject nicht das Treiberobjekt des Zielgeräts sein. Es sollte vielmehr das Treiberobjekt des Treibers sein, der CallbackRoutine implementiert.

[in] CallbackRoutine

Ein Zeiger auf die PnP-Benachrichtigungsrückrufroutine, die aufgerufen werden soll, wenn das angegebene PnP-Ereignis auftritt.

Der Funktionsprototyp für diese Rückrufroutine ist wie folgt definiert:

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

Die NotificationStructure der Rückrufroutine ist spezifisch für den EventCategory-Wert , wie in der folgenden Tabelle gezeigt.

Ereigniskategorie	Benachrichtigungsstruktur
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION Weitere Informationen finden Sie unter Verwenden von PnP-Benachrichtigungen und TARGET_DEVICE_CUSTOM_NOTIFICATION.

Der Context-Parameter der Rückrufroutine enthält die Kontextdaten, die der Treiber während der Registrierung angegeben hat.

Informationen zum Einschließen einer Funktionsdeklaration für die Rückrufroutine, die die Anforderungen von Static Driver Verifier (SDV) erfüllt, finden Sie unter Beispiele.

Der PnP-Manager ruft Treiberrückrufroutinen unter IRQL = PASSIVE_LEVEL auf.

[in, optional] Context

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der Kontext enthält, den der PnP-Manager an die Rückrufroutine übergibt.

[out] NotificationEntry

Ein Zeiger auf einen undurchsichtigen Wert, der von diesem Aufruf zurückgegeben wird, der die Registrierung identifiziert. Übergeben Sie diesen Wert an die IoUnregisterPlugPlayNotificationEx-Routine , um die Registrierung zu entfernen.

Rückgabewert

IoRegisterPlugPlayNotification gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück.

Hinweise

Ein Treiber registriert sich für eine Ereigniskategorie. Jede Kategorie enthält einen oder mehrere Typen von PnP-Ereignissen.

Ein Treiber kann verschiedene Rückrufroutinen für verschiedene Ereigniskategorien registrieren oder eine einzelne Rückrufroutine registrieren. Eine einzelne Rückrufroutine kann die NotificationStructure in eine PLUGPLAY_NOTIFICATION_HEADER umwandeln und das Ereignisfeld verwenden, um den genauen Typ der Benachrichtigungsstruktur zu bestimmen.

Wenn der Aufrufer PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES angibt, kann das Betriebssystem die PnP-Benachrichtigungsrückrufroutine für ein einzelnes EventCategoryDeviceInterfaceChange-Ereignis für eine vorhandene Schnittstelle zweimal aufrufen. Sie können den zweiten Rückruf problemlos ignorieren. Das Betriebssystem ruft den Rückruf nicht mehr als zweimal für ein einzelnes Ereignis auf.

PnP-Benachrichtigungsrückrufroutinen sollten ihre Aufgaben so schnell wie möglich erledigen und die Kontrolle an den PnP-Manager zurückgeben, um Verzögerungen bei der Benachrichtigung anderer Treiber und Anwendungen zu verhindern, die sich für das Ereignis registriert haben.

Der PnP-Manager nimmt keinen Verweis auf das Dateiobjekt aus, wenn sich ein Treiber für die Benachrichtigung über ein EventCategoryTargetDeviceChange-Ereignis registriert. Wenn die PnP-Benachrichtigungsrückrufroutine des Treibers Zugriff auf das Dateiobjekt erfordert, sollte der Treiber vor dem Aufrufen von IoRegisterPlugPlayNotification einen zusätzlichen Verweis auf das Dateiobjekt erstellen.

In der Regel sollten Kernel-Mode kmDF-Treiber (Driver Framework) IoRegisterPlugPlayNotification über ihre EvtDeviceSelfManagedIoInit-Rückruffunktion und IoUnregisterPlugPlayNotification über ihre EvtDeviceSelfManagedIoCleanup-Rückruffunktion aufrufen. Diese Treiber sollten IoRegisterPlugPlayNotificationnicht über ihre Rückruffunktion EvtDriverDeviceAdd aufrufen. Andernfalls wird die PnP-Benachrichtigungsrückrufroutine möglicherweise aufgerufen, bevor der Treiberstapel von PnP gestartet wird. In diesem Fall ist der Treiber nicht bereit, die Benachrichtigung zu verarbeiten.

Weitere Informationen finden Sie unter Verwenden von PnP-Benachrichtigungen.

Beispiele

Um eine PnP-Benachrichtigungsrückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen 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 PnP-Benachrichtigungsrückrufroutine mit dem Namen MyCallbackRoutinezu definieren, verwenden Sie den typ DRIVER_NOTIFICATION_CALLBACK_ROUTINE, wie in diesem Codebeispiel gezeigt:

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

Der DRIVER_NOTIFICATION_CALLBACK_ROUTINE Funktionstyp ist in der Wdm.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 DRIVER_NOTIFICATION_CALLBACK_ROUTINE 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 WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)