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
Zeigen Sie auf das Treiberobjekt, das zur DriverEntry- Routine des Treibers eingegeben wurde.
[in, optional] DriverList
Verweist optional auf einen vom Aufrufer bereitgestellten Puffer, der die Ressourcenliste des Treibers enthält, wenn der Treiber die gleichen Ressourcen für alle Geräte angibt. Wenn der Aufrufer eine DeviceList-angibt, wird dieser Parameter ignoriert.
[in, optional] DriverListSize
Gibt die Größe in Byte einer optionalen DriverList-an. Wenn DriverList-NULL-ist, sollte dieser Parameter null 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
Verweist 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 angibt, kann der Aufrufer stattdessen eine DriverList- angeben.
[in, optional] DeviceListSize
Gibt die Größe in Byte eines optionalen DeviceList-an. Wenn DeviceList-NULL-ist, sollte dieser Parameter null sein.
[out] ConflictDetected
Zeiger auf einen vom Aufrufer bereitgestellten booleschen Wert, der 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-enumerierbares Gerät erforderlich sind. |
| STATUS_UNSUCCESSFUL | Die DeviceList- oder DriverList- ist ungültig. |
Bemerkungen
Diese Routine richtet sich an Treiber, die frühere Hardware erkennen, die nicht durch Plug and Play (PnP) aufgezählt werden kann.
Wenn ein Treiber nur PnP-Hardware unterstützt, wird keine Erkennung durchgeführt und daher nicht IoReportResourceForDetectionaufgerufen. Das PnP-System listet jedes PnP-Gerät auf, weist dem Gerät Ressourcen zu und übergibt diese Ressourcen an die Treiber des Geräts in einer IRP_MN_START_DEVICE Anforderung.
Wenn ein PnP-Treiber jedoch Legacyhardware unterstützt, muss er IoReportResourceForDetection- aufrufen, um Hardwareressourcen in Anspruch zu nehmen, bevor versucht wird, das Gerät zu erkennen.
Aufrufer dieser Routine geben eine CM_RESOURCE_LIST entweder in einer DeviceList- oder einer DriverList- an, die aus aus dem ausgelagertem Speicher zugewiesen wird und aus unformatierten, nicht übersetzten Ressourcen besteht. Der Anrufer ist dafür verantwortlich, den Speicher freizugeben.
Ein Treiber, der mehrere ältere Karten gleichzeitig steuern kann, sollte die Ressourcen für jedes Gerät für das jeweilige Gerät beanspruchen (mithilfe der DeviceObject-, DeviceList-und DeviceListSize Parameter). 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 eine Standardgröße von 1. Wenn eines der Arrays mehrere Elemente aufweist, muss der Aufrufer Speicher dynamisch zuweisen, um die zusätzlichen Elemente zu enthalten. Nur ein CM_PARTIAL_RESOURCE_DESCRIPTOR kann Teil jeder 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.
IoReportResourceForDetectionbestimmt mit Hilfe des PnP-Managers, ob die angeforderten Ressourcen mit Ressourcen in Konflikt stehen, die bereits beansprucht wurden.
Wenn ein Konflikt erkannt wird, legt diese Routine den BOOLEAN bei ConflictDetected auf TRUE- fest und gibt STATUS_CONFLICTING_ADDRESSES zurück.
Wenn kein Konflikt erkannt wird, ruft diese Routine die Ressourcen auf, legt den BOOLEAN bei 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 IoReportDetectedDeviceaufruft. In diesem Aufruf legt der Treiber ResourceAssigned- auf TRUE fest, sodass der PnP-Manager nicht erneut versucht, die Ressourcen abzurufen.
Wenn ein Treiber die von einem Aufruf dieser Routine beanspruchten Ressourcen nicht mehr erfordert, ruft der Treiber diese Routine erneut mit einer DriverList- oder DeviceList- mit einer Count von Null auf.
Wenn ein Treiber Ressourcen auf gerätespezifischer Basis für mehrere Geräte angibt, muss der Treiber diese Routine für jedes gerät aufrufen.
Ein Treiber kann diese Routine mehrmals für ein bestimmtes Gerät aufrufen. Wenn eine Gruppe von Ressourcen fehlschlägt, kann der Treiber die Routine erneut für dasselbe Gerät mit einer anderen Gruppe von Ressourcen aufrufen. Wenn eine Reihe von Ressourcen erfolgreich ist, kann der Treiber diese Routine erneut mit einer neuen Liste 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- | Universal |
| Header- | ntddk.h (include Ntddk.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |