IoReportResourceForDetection-Funktion (ntddk.h)

Die IoReportResourceForDetection-Routine beansprucht Hardwareressourcen in der Konfigurationsregistrierung für ein Legacygerät.

Syntax

NTSTATUS IoReportResourceForDetection(
  [in]           PDRIVER_OBJECT    DriverObject,
  [in, optional] PCM_RESOURCE_LIST DriverList,
  [in, optional] ULONG             DriverListSize,
  [in, optional] PDEVICE_OBJECT    DeviceObject,
  [in, optional] PCM_RESOURCE_LIST DeviceList,
  [in, optional] ULONG             DeviceListSize,
  [out]          PBOOLEAN          ConflictDetected
);

Parameter

[in] DriverObject

Zeiger auf das Treiberobjekt, das in die DriverEntry-Routine des Treibers eingegeben wurde.

[in, optional] DriverList

Zeigt optional auf einen vom Aufrufer bereitgestellten Puffer, der die Ressourcenliste des Treibers enthält, wenn der Treiber dieselben Ressourcen für alle geräte beansprucht. Wenn der Aufrufer eine DeviceList angibt, wird dieser Parameter ignoriert.

[in, optional] DriverListSize

Gibt die Größe einer optionalen DriverList in Bytes an. Wenn DriverListNULL ist, sollte dieser Parameter 0 sein.

[in, optional] DeviceObject

Zeigt optional auf das Geräteobjekt, das das Gerät darstellt, für das der Treiber versucht, Ressourcen in Anspruch zu nehmen.

[in, optional] DeviceList

Zeigt optional auf einen vom Aufrufer bereitgestellten Puffer, der die Ressourcenliste des Geräts enthält. Wenn der Treiber die gleichen Ressourcen für alle geräte beansprucht, kann der Aufrufer stattdessen eine DriverList angeben.

[in, optional] DeviceListSize

Gibt die Größe einer optionalen DeviceList in Bytes an. Wenn DeviceListNULL ist, sollte dieser Parameter 0 sein.

[out] ConflictDetected

Zeiger auf einen vom Aufrufer bereitgestellten booleschen Wert, der bei der Rückgabe auf TRUE festgelegt ist, wenn die Ressourcen nicht verfügbar sind.

Rückgabewert

IoReportResourceForDetection gibt STATUS_SUCCESS zurück, wenn die Ressourcen beansprucht werden. Mögliche Fehlerrückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_CONFLICTING_ADDRESSES	Die Ressourcen konnten nicht beansprucht werden, da sie bereits verwendet werden oder für ein PnP-aufzählbares Gerät benötigt werden.
STATUS_UNSUCCESSFUL	DeviceList oder DriverList ist ungültig.

Hinweise

Diese Routine gilt für Treiber, die frühere Hardware erkennen, die nicht von Plug & Play (PnP) aufgezählt werden kann.

Wenn ein Treiber nur PnP-Hardware unterstützt, führt er keine Erkennung durch und ruft daher nicht IoReportResourceForDetection auf. Das PnP-System listet jedes PnP-Gerät auf, weist dem Gerät Ressourcen zu und übergibt diese Ressourcen in einer IRP_MN_START_DEVICE Anforderung an die Treiber des Geräts.

Wenn ein PnP-Treiber jedoch Legacyhardware unterstützt, muss er IoReportResourceForDetection aufrufen, um Hardwareressourcen in Anspruch zu nehmen, bevor er versucht, das Gerät zu erkennen.

Aufrufer dieser Routine geben eine CM_RESOURCE_LIST in einer DeviceList oder einer DriverList an, die aus ausgelagertem Arbeitsspeicher zugeordnet ist und aus unformatierten, nicht übersetzten Ressourcen besteht. Der Aufrufer ist für die Freigabe des Arbeitsspeichers verantwortlich.

Ein Treiber, der mehrere Ältere Karte gleichzeitig steuern kann, sollte die Ressourcen für jedes Gerät gegen das Geräteobjekt für das jeweilige Gerät beanspruchen (mit den Parametern DeviceObject, DeviceList und DeviceListSize). Ein solcher Treiber darf diese Ressourcen nicht gegen sein Treiberobjekt beanspruchen.

Eine CM_RESOURCE_LIST enthält zwei Arrays mit variabler Größe. Jedes Array hat die Standardgröße 1. Wenn eines der Arrays über mehrere Elemente verfügt, muss der Aufrufer den Arbeitsspeicher dynamisch zuordnen, um die zusätzlichen Elemente zu enthalten. Nur ein CM_PARTIAL_RESOURCE_DESCRIPTOR kann Teil jedes CM_FULL_RESOURCE_DESCRIPTOR in der Liste sein, mit Ausnahme des letzten vollständigen Ressourcendeskriptors im CM_RESOURCE_LIST, der zusätzliche partielle Ressourcendeskriptoren in seinem Array aufweisen kann.

IoReportResourceForDetection bestimmt mithilfe des PnP-Managers, ob die angeforderten Ressourcen in Konflikt mit bereits beanspruchten Ressourcen stehen.

Wenn ein Konflikt erkannt wird, legt diese Routine den BOOLEAN unter ConflictDetected auf TRUE fest und gibt STATUS_CONFLICTING_ADDRESSES zurück.

Wenn kein Konflikt erkannt wird, beansprucht diese Routine die Ressourcen, legt den BOOLEAN unter ConflictDetected auf FALSE fest und gibt STATUS_SUCCESS zurück.

Wenn diese Routine erfolgreich ist und der Treiber ein Älteres Gerät erkennt, meldet der Treiber das Gerät an den PnP-Manager, indem er IoReportDetectedDevice aufruft. In diesem Aufruf legt der Treiber ResourceAssigned auf TRUE fest, sodass der PnP-Manager nicht versucht, die Ressourcen erneut abzurufen.

Wenn ein Treiber die Durch einen Aufruf dieser Routine beanspruchten Ressourcen nicht mehr benötigt, ruft der Treiber diese Routine erneut mit einer DriverList oder DeviceList mit einer Anzahl von 0 auf.

Wenn ein Treiber Ressourcen auf gerätespezifischer Basis für mehrere Geräte beansprucht, muss der Treiber diese Routine für jedes gerät aufrufen.

Ein Treiber kann diese Routine für ein bestimmtes Gerät mehrmals aufrufen. Wenn eine Gruppe von Ressourcen ausfällt, kann der Treiber die Routine für dasselbe Gerät mit einem anderen Ressourcensatz erneut aufrufen. Wenn eine Reihe von Ressourcen erfolgreich ist, kann der Treiber diese Routine mit einer neuen Liste erneut aufrufen. die neue Liste ersetzt die vorherige Liste.

Aufrufer von IoReportResourceForDetection müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	ntddk.h (include Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt Hinweise)

Weitere Informationen

CM_RESOURCE_LIST

IoReportDetectedDevice