IoReportTargetDeviceChange-Funktion (wdm.h)

  • Artikel

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
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 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)

Weitere Informationen

IoReportTargetDeviceChangeAsynchronous

TARGET_DEVICE_CUSTOM_NOTIFICATION