IoReportRootDevice-Funktion (ntddk.h)

Artikel
02/29/2024

Die IoReportRootDevice-Routine meldet ein Gerät, das von einem PnP-Bustreiber nicht erkannt werden kann, an den PnP-Manager. IoReportRootDevice ermöglicht es, nur ein Gerät pro Treiber zu erstellen.

Syntax

NTSTATUS IoReportRootDevice(
  [in] PDRIVER_OBJECT DriverObject
);

Parameter

[in] DriverObject

Zeiger auf das Treiberobjekt des Treibers, der das Gerät erkannt hat.

Rückgabewert

IoReportRootDevice gibt STATUS_SUCCESS bei Erfolg oder den entsprechenden Fehlercode bei Einem Fehler zurück.

Hinweise

Treiber für Geräte, die von einem PnP-Bustreiber nicht erkannt werden können, verwenden IoReportRootDevice , um ihr Gerät an das System zu melden. Geräte, die von einem PnP-Bustreiber erkannt werden können, sollten als Reaktion auf eine IRP_MN_QUERY_DEVICE_RELATIONS-Anforderung gemeldet werden.

Ein Treiber ruft diese Routine in der Regel aus seiner DriverEntry-Routine auf.

IoReportRootDevice markiert das Gerät als root-enumeriertes Gerät, und diese Identifizierung ist über Systemboote hinweg persistent. Der PnP-Manager "erkennt" das Gerät in der Stammliste und konfiguriert es wie ein PnP-Gerät: Der PnP-Manager fragt Geräteinformationen ab, identifiziert die entsprechenden Treiber, ruft deren AddDevice-Routinen auf und sendet alle entsprechenden PnP-IRPs.

Das System generiert eine einzelne Hardware-ID-Zeichenfolge für das Gerät im Format ROOT\Driver , wobei Driver der Dienstname des Treibers ist. Ein Treiber kann zusätzliche Hardware-IDs oder kompatible IDs bereitstellen, indem er die IRP_MN_QUERY_ID-Anforderung verarbeitet.

Ein Treiberwriter muss eine INF-Datei bereitstellen, die mit einer der angegebenen Hardware-IDs oder kompatiblen IDs übereinstimmt. Die INF-Datei sollte den ursprünglichen Treiber angeben, der IoReportRootDevice als Treiber aufgerufen hat, der für diese IDs geladen werden soll. Das System verwendet diese Informationen, um den Treiberstapel für das Gerät neu zu erstellen, z. B. beim Neustart. Aufrufer von IoReportRootDevice müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden.

Treiber sollten IoReportDetectedDevice verwenden, um Hardwaregeräte zu melden, die Ressourcen verwenden, aber nicht von einem PnP-Bustreiber anstelle von IoReportRootDevice erkannt werden können.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 8 und höheren Versionen von Windows.
Zielplattform	Universell
Header	ntddk.h (include Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")