IoReportTargetDeviceChange-Funktion (wdm.h)
Die IoReportTargetDeviceChange Routine benachrichtigt den PnP-Manager, dass ein benutzerdefiniertes Ereignis auf einem Gerät aufgetreten ist.
Syntax
NTSTATUS IoReportTargetDeviceChange(
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] PVOID NotificationStructure
);
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.
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.
Rückgabewert
IoReportTargetDeviceChange gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. Mögliche Fehlerstatuswerte sind:
| Rückgabecode | Beschreibung |
|---|---|
|
Der Aufrufer hat ein PnP-Systemereignis angegeben, z. B. GUID_TARGET_DEVICE_QUERY_REMOVE. Diese Routine ist nur für benutzerdefinierte Ereignisse vorgesehen. |
Bemerkungen
Nachdem IoReportTargetDeviceChange den PnP-Manager benachrichtigt, dass ein benutzerdefiniertes Ereignis auf einem Gerät aufgetreten ist, sendet der PnP-Manager Benachrichtigungen über das Ereignis an Treiber, die für die Benachrichtigung auf dem Gerät registriert sind. 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 IoReportTargetDeviceChange 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.
Ein Treiber sollte die asynchrone Form dieser Routine aufrufen, IoReportTargetDeviceChangeAsynchronousanstelle dieser Routine, um Deadlocks zu verhindern.
Bestimmte Kernelmoduskomponenten können diese synchrone Routine aufrufen. Ein Dateisystem kann z. B. IoReportTargetDeviceChange- aufrufen, um ein benutzerdefiniertes Ereignis "Get off the volume" zu melden, wenn eine Komponente versucht, das Volume für exklusiven Zugriff zu öffnen. Clients, die sich für Benachrichtigungen auf Dateisystemvolumes registrieren, achten darauf, keine exklusive Öffnung in einer PnP-Benachrichtigungsrückrufroutine anzufordern.
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.
Aufrufer von IoReportTargetDeviceChange- müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden. Rufen Sie IoReportTargetDeviceChangeAsynchroneauf, um eine Änderung des Zielgeräts von IRQL-> PASSIVE_LEVEL zu melden.
IoReportTargetDeviceChangechange wird unter Windows 98/Me nicht unterstützt; sie gibt STATUS_NOT_IMPLEMENTED zurück.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Ab Windows 2000 verfügbar. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |