IoRegisterPlugPlayNotification-Funktion (wdm.h)

Die IoRegisterPlugPlayNotification Routine registriert eine Plug and Play (PnP)-Benachrichtigungsrückrufroutine, 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 die die Rückrufroutine registriert wird.

[in] EventCategoryFlags

Kennzeichnen sie Bits, die den Registrierungsvorgang ändern. Mögliche Werte sind:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Nur gültig mit einem EventCategory- von EventCategoryDeviceInterfaceChange. Wenn festgelegt, ruft der PnP-Manager die Treiberrückrufroutine für jede Aktuell registrierte und aktive Geräteschnittstelleninstanz auf und registriert die Rückrufroutine für zukünftige Ankunfts- 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 unterschiedliche EventCategory Werte:

• Wenn EventCategoryEventCategoryDeviceInterfaceChangeist, muss EventCategoryData- auf eine GUID verweisen, die eine Geräteschnittstellenklasse angibt. CallbackRoutine- wird aufgerufen, wenn eine Schnittstelle dieser Klasse aktiviert oder entfernt wird.

• Wenn EventCategoryEventCategoryHardwareProfileChangeist, muss EventCategoryData-NULL-sein.

• Wenn EventCategoryEventCategoryTargetDeviceChangeist, muss EventCategoryData- auf das Dateiobjekt verweisen, für das PnP-Benachrichtigung angefordert wird.

[in] DriverObject

Ein Zeiger auf das Treiberobjekt des Aufrufers.

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

Für EventCategoryTargetDeviceChangedarf DriverObject- nicht das Treiberobjekt des Zielgeräts sein; Es sollte vielmehr das Treiberobjekt des Treibers sein, das CallbackRoutineimplementiert.

[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 dargestellt.

Der parameter Context der Rückrufroutine enthält die Kontextdaten, die der Treiber während der Registrierung bereitgestellt 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 bei 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 Fehlerstatus zurück.

Bemerkungen

Ein Treiber registriert sich für eine Ereigniskategorie. Jede Kategorie enthält mindestens einen PnP-Ereignistyp.

Ein Treiber kann unterschiedliche 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 Feld Event verwenden, um den genauen Typ der Benachrichtigungsstruktur zu bestimmen.

Wenn der Aufrufer PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES angibt, ruft das Betriebssystem die PnP-Benachrichtigungsrückrufroutine für ein einzelnes EventCategoryDeviceInterfaceChange-Ereignis für eine vorhandene Schnittstelle zweimal auf. Sie können den zweiten Aufruf des Rückrufs sicher 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 ausführen und die Steuerung 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 entfernt keinen Verweis auf das Dateiobjekt, wenn sich ein Treiber für die Benachrichtigung eines EventCategoryTargetDeviceChange-Ereignisses registriert. Wenn die PnP-Benachrichtigungsrückrufroutine des Treibers Zugriff auf das Dateiobjekt erfordert, sollte der Treiber einen zusätzlichen Verweis auf das Dateiobjekt herausnehmen, bevor IoRegisterPlugPlayNotificationaufgerufen wird.

In der Regel sollten Kernel-Mode Driver Framework (KMDF)-Treiber IoRegisterPlugPlayNotification aus ihrer EvtDeviceSelfManagedIoInit Rückruffunktion aufrufen und IoUnregisterPlugPlayNotification- aus ihrer EvtDeviceSelfManagedIoCleanup Rückruffunktion aufrufen. Diese Treiber sollten nicht Aufrufen IoRegisterPlugPlayNotification aus ihrer EvtDriverDeviceAdd Rückruffunktion; 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 Using PnP Notification.

Beispiele

Um eine PnP-Benachrichtigungsrückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückrufroutinen identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen 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 PnP-Benachrichtigungsrückrufroutine zu definieren, die MyCallbackRoutinebenannt ist, verwenden Sie den DRIVER_NOTIFICATION_CALLBACK_ROUTINE Typ, 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 wird in der Wdm.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 DRIVER_NOTIFICATION_CALLBACK_ROUTINE Funktionstyp 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 WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Anforderungen

Siehe auch

Verwenden von PnP-Benachrichtigungs-

DEVICE_INTERFACE_CHANGE_NOTIFICATION

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

HWPROFILE_CHANGE_NOTIFICATION

IoUnregisterPlugPlayNotification-

IoUnregisterPlugPlayNotificationEx

PLUGPLAY_NOTIFICATION_HEADER

TARGET_DEVICE_CUSTOM_NOTIFICATION

TARGET_DEVICE_REMOVAL_NOTIFICATION