IoReportTargetDeviceChange-Funktion (wdm.h)
Die IoReportTargetDeviceChange-Routine benachrichtigt den PnP-Manager, dass auf einem Gerät ein benutzerdefiniertes Ereignis aufgetreten ist.
Syntax
NTSTATUS IoReportTargetDeviceChange(
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] PVOID NotificationStructure
);
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.
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.
Rückgabewert
IoReportTargetDeviceChange gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. Mögliche Fehler status Werte:
| Rückgabecode | Beschreibung |
|---|---|
|
Der Aufrufer hat ein PnP-Systemereignis angegeben, z. B. GUID_TARGET_DEVICE_QUERY_REMOVE. Diese Routine gilt nur für benutzerdefinierte Ereignisse. |
Hinweise
Nachdem IoReportTargetDeviceChange den PnP-Manager benachrichtigt hat, dass auf einem Gerät ein benutzerdefiniertes Ereignis aufgetreten ist, sendet der PnP-Manager eine Benachrichtigung über das Ereignis an Treiber, 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 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 anstelle dieser Routine die asynchrone Form dieser Routine, IoReportTargetDeviceChangeAsynchronous, aufrufen, um Deadlocks zu verhindern.
Bestimmte Kernelmoduskomponenten können diese synchrone Routine aufrufen. Beispielsweise kann ein Dateisystem 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 generieren (die im Microsoft Windows SDK enthalten sind).
Aufrufer von IoReportTargetDeviceChange müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden. Rufen Sie IoReportTargetDeviceChangeAsynchronous auf, um eine Änderung des Zielgeräts von IRQL > PASSIVE_LEVEL zu melden.
IoReportTargetDeviceChange wird unter Windows 98/Me nicht unterstützt. es gibt STATUS_NOT_IMPLEMENTED zurück.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar ab Windows 2000. |
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |