IoReportTargetDeviceChangeAsynchronous-Funktion (wdm.h)

  • Artikel

Die IoReportTargetDeviceChangeAsynchronous-Routine benachrichtigt den PnP-Manager, dass auf einem Gerät ein benutzerdefiniertes Ereignis 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 gemeldeten Geräts.

[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 sich für die Benachrichtigung über das Ereignis registriert haben.

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. Weitere Informationen finden Sie im Abschnitt Hinweise zu Den Anforderungen für Zuordnungspools.

NotificationStructure. FileObject muss NULL sein. NotificationStructure. Das 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 NotificationStructure aus. FileObject-Feld , wenn Benachrichtigungen an Registranten gesendet werden.

[in, optional] Callback

Verweist optional auf eine vom Aufrufer bereitgestellte Routine, die der PnP-Manager aufruft, nachdem er die Treiber benachrichtigt, die sich für dieses benutzerdefinierte Ereignis registriert haben.

Die Rückrufroutine hat den folgenden Typ:

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

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

Der PnP-Manager ruft geräteseitige Rückrufroutinen unter IRQL = PASSIVE_LEVEL auf.

[in, out] Context

Verweist optional auf eine vom Aufrufer bereitgestellte Kontextstruktur, die der PnP-Manager an die Rückrufroutine übergibt. Der Aufrufer muss diese Struktur aus dem nicht auslagerten Arbeitsspeicher zuordnen.

Rückgabewert

Rückgabecode Beschreibung
STATUS_INVALID_DEVICE_REQUEST Der Aufrufer hat ein PnP-Systemereignis angegeben, z. B. GUID_TARGET_DEVICE_QUERY_REMOVE. Diese Routine gilt nur für benutzerdefinierte Ereignisse.

Hinweise

Nachdem die IoReportTargetDeviceChangeAsynchronous-Routine den PnP-Manager benachrichtigt hat, dass auf einem Gerät ein benutzerdefiniertes Ereignis aufgetreten ist, wird die Routine sofort zurückgegeben. Es wartet nicht, während der PnP-Manager eine Benachrichtigung über das Ereignis an Treiber sendet, die sich für die Benachrichtigung auf dem Gerät registriert haben. 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 generieren (die im Microsoft Windows SDK enthalten sind).

Wenn ein Treiber diese Routine während der Behandlung eines Ereignisses, einer IRP_MN_REMOVE_DEVICE oder eines IRP_MN_SURPRISE_REMOVAL aufruft, ruft der PnP-Manager die Rückrufroutine des Fahrers auf, nachdem der Fahrer zurückkehrt und der Stapel entladen wird.

Aufrufer von IoReportTargetDeviceChangeAsynchronous müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Wenn ein Treiberwriter diese Routine unter IRQL = DISPATCH_LEVEL aufruft, muss die NotificationStructure aus dem nicht auslagerten Arbeitsspeicher zugeordnet werden.

Anforderungen

Anforderung Wert
Zielplattform Universell
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln HwStorPortProhibitedDIs(storport)

Weitere Informationen

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION