IoReportTargetDeviceChangeAsynchronous-Funktion (wdm.h)

Die IoReportTargetDeviceChangeAsynchronous Routine benachrichtigt den PnP-Manager, dass ein benutzerdefiniertes Ereignis auf einem Gerät aufgetreten ist.

Syntax

NTSTATUS IoReportTargetDeviceChangeAsynchronous(
  [in]           PDEVICE_OBJECT                   PhysicalDeviceObject,
  [in]           PVOID                            NotificationStructure,
  [in, optional] PDEVICE_CHANGE_COMPLETE_CALLBACK Callback,
  [in, out]      PVOID                            Context
);

Parameter

[in] PhysicalDeviceObject

Zeiger auf die PDO des geräts, das gemeldet wird.

[in] NotificationStructure

Zeiger auf eine vom Aufrufer bereitgestellte TARGET_DEVICE_CUSTOM_NOTIFICATION Struktur, die das benutzerdefinierte Ereignis beschreibt. Der PnP-Manager sendet diese Struktur an Treiber, die für die Benachrichtigung über das Ereignis registriert wurden.

Diese vom Aufrufer bereitgestellte Struktur kann freigegeben werden, sobald die Routine zurückgegeben wird, da der PnP-Manager eine flache Kopie erstellt und die Kopie verwendet, um Treiber zu benachrichtigen. Die Kopie wird automatisch vom PnP-Manager freigegeben, sobald sie nicht mehr benötigt wird. Siehe Abschnitt "Hinweise" zu den Anforderungen an den Zuweisungspool.

NotificationStructure.FileObject- muss NULL-sein. NotificationStructure.Ereignis- muss die benutzerdefinierte GUID für das Ereignis enthalten. Die anderen Felder der NotificationStructure müssen entsprechend dem benutzerdefinierten Ereignis ausgefüllt werden.

Der PnP-Manager füllt die NotificationStructureaus.FileObject Feld, wenn es Benachrichtigungen an Registranten sendet.

[in, optional] Callback

Verweist optional auf eine vom Aufrufer bereitgestellte Routine, die der PnP-Manager aufruft, nachdem er beendet hat, Treiber zu benachrichtigen, die für dieses benutzerdefinierte Ereignis registriert wurden.

Die Rückrufroutine weist den folgenden Typ auf:

typedef
VOID
(*PDEVICE_CHANGE_COMPLETE_CALLBACK)(
    IN PVOID Context
    );

Eine rückrufbasierte Rückrufroutine für Geräteänderungen sollte nicht blockiert werden und darf keine synchronen Routinen aufrufen, die PnP-Ereignisse generieren.

Der PnP-Manager ruft geräteverändernde Rückrufroutinen bei IRQL = PASSIVE_LEVEL auf.

[in, out] Context

Verweist optional auf eine vom Aufrufer bereitgestellte Kontextstruktur, die der PnP-Manager an die Callback- Routine übergibt. Der Aufrufer muss diese Struktur aus nicht seitenfreiem Speicher zuordnen.

Rückgabewert

Bemerkungen

Nachdem die IoReportTargetDeviceChangeAsynchronous Routine den PnP-Manager benachrichtigt, dass ein benutzerdefiniertes Ereignis auf einem Gerät aufgetreten ist, wird die Routine sofort zurückgegeben; Es wartet nicht, während der PnP-Manager Benachrichtigungen über das Ereignis an Treiber sendet, die für die Benachrichtigung auf dem Gerät registriert wurden. Verwenden Sie diese Routine nicht, um System-PnP-Ereignisse wie GUID_TARGET_DEVICE_REMOVE_COMPLETE zu melden.

Ein Treiber, der ein benutzerdefiniertes Geräteereignis definiert, ruft IoReportTargetDeviceChangeAsynchronous auf, um den PnP-Manager darüber zu informieren, dass das benutzerdefinierte Ereignis aufgetreten ist. Benutzerdefinierte Benachrichtigungen können für Ereignisse wie eine Änderung der Volumebezeichnung verwendet werden.

Die benutzerdefinierte Benachrichtigungsstruktur enthält ein treiberdefiniertes Ereignis mit eigener GUID. Treiberautoren können GUIDs mit Uuidgen.exe oder Guidgen.exe (die im Microsoft Windows SDK enthalten sind) generieren.

Wenn ein Treiber diese Routine während der Behandlung eines Ereignisses, eines IRP_MN_REMOVE_DEVICEoder eines IRP_MN_SURPRISE_REMOVALaufruft, ruft der PnP-Manager die Callback- Routine des Treibers auf, nachdem der Treiber zurückgegeben wird und der Stapel sich entspannt.

Aufrufer von IoReportTargetDeviceChangeAsynchronous müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Wenn ein Treiberschreiber diese Routine bei IRQL = DISPATCH_LEVEL aufruft, muss die NotificationStructure- aus nicht seitengebundenem Speicher zugewiesen werden.

Anforderungen

Siehe auch

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION