IO_RESOURCE_REQUIREMENTS_LIST-Struktur (wdm.h)

Artikel
03/08/2023

Die IO_RESOURCE_REQUIREMENTS_LIST-Struktur beschreibt Sätze von Ressourcenkonfigurationen, die von einem Gerät verwendet werden können. Jede Konfiguration stellt eine Reihe von Rohressourcen verschiedener Typen dar, die von einem Gerät verwendet werden können.

Syntax

typedef struct _IO_RESOURCE_REQUIREMENTS_LIST {
  ULONG            ListSize;
  INTERFACE_TYPE   InterfaceType;
  ULONG            BusNumber;
  ULONG            SlotNumber;
  ULONG            Reserved[3];
  ULONG            AlternativeLists;
  IO_RESOURCE_LIST List[1];
} IO_RESOURCE_REQUIREMENTS_LIST, *PIO_RESOURCE_REQUIREMENTS_LIST;

Member

ListSize

Die Gesamtzahl der Bytes, die die IO_RESOURCE_REQUIREMENTS_LIST-Struktur , ihr IO_RESOURCE_LIST-Array und deren IO_RESOURCE_DESCRIPTOR-Arrays bilden.

InterfaceType

Gibt einen Schnittstellentyp an. Dies muss einer der Typen sein, die von INTERFACE_TYPE in Wdm.h oder Ntddk.h definiert werden. (Wird nicht von WDM-Treibern verwendet.)

BusNumber

Eine systemseitig zugewiesene, nullbasierte Busnummer. (Wird nicht von WDM-Treibern verwendet.)

SlotNumber

Eine Systemslotnummer. (Wird nicht von WDM-Treibern verwendet.)

Reserved[3]

Reserviert.

AlternativeLists

Die Anzahl alternativer Listen (oder Konfigurationen) von Hardwareressourcen, die von dieser IO_RESOURCE_REQUIREMENTS_LIST-Struktur beschrieben werden. Das List-Element ist der Header für die erste alternative Liste.

List[1]

Die IO_RESOURCE_LIST Struktur, die als Header für die erste alternative Liste der Hardwareressourcen dient. Wenn die IO_RESOURCE_REQUIREMENTS_LIST-Struktur mehr als eine alternative Liste beschreibt, folgt die zweite Alternative Liste sofort der ersten alternativen Liste im Arbeitsspeicher usw. Die Größe jeder alternativen Liste hängt von der Länge des IO_RESOURCE_DESCRIPTOR Arrays ab, das sie enthält. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Hinweise

Diese Struktur wird vom IRP_MN_FILTER_RESOURCE_REQUIREMENTS und IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRPs verwendet, um eine oder mehrere alternative Konfigurationen von Hardwareressourcen zu beschreiben.

Die IO_RESOURCE_REQUIREMENTS_LIST-Struktur ist ein Header für eine größere Datenstruktur mit variabler Größe, die eine oder mehrere alternative Ressourcenlisten angibt. Alle Daten in dieser größeren Struktur belegen einen zusammenhängenden Speicherblock, dessen Größe vom ListSize-Element angegeben wird. Jede alternative Liste belegt einen Teilblock innerhalb des größeren Blocks.

Jede alternative Liste beginnt mit einer IO_RESOURCE_LIST-Struktur , die als Header für ein Array von IO_RESOURCE_DESCRIPTOR Strukturen dient. Die Länge dieses Arrays bestimmt die Größe der Liste, die von einer alternativen Liste zur nächsten variieren kann. Treibercode kann die Zeigerarithmetik verwenden, um von einer alternativen Liste zur nächsten zu wechseln. Wenn beispielsweise ein Parameter namens list ein Zeiger auf die IO_RESOURCE_LIST-Struktur am Anfang einer alternativen Liste ist, kann die Liste wie folgt aktualisiert werden, um auf den Anfang der nächsten Liste zu verweisen:

list = (PIO_RESOURCE_LIST)(list->Descriptors + list->Count);

In diesem Beispiel list->Descriptors ist ein Zeiger auf den Anfang des IO_RESOURCE_DESCRIPTOR-Arrays und list->Count die Anzahl der Elemente im Array. Weitere Informationen zu den Membern Deskriptors und Count finden Sie unter IO_RESOURCE_LIST.

Beispiele

Wenn ein Treiber einen Handler für eine IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP enthält, führt der Handler in der Regel die Ressourcenliste durch, auf die das Feld IoStatus.Information im IRP verweist. Das folgende Codebeispiel enthält eine Funktion mit dem Namen FilterResources, die im Handler aufgerufen wird, um die Liste zu durchlaufen. Diese Funktion überprüft entweder, ob eine bestimmte Ressource in der Liste angegeben ist, oder ändert die Ressourcenanforderungen in der Liste, ohne die Größe der Liste zu ändern. (Eine Funktion, die die Größe der Liste ändert, muss einen Puffer für die aktualisierte Liste zuweisen, die Liste in diesen Puffer schreiben, das Feld IoStatus.Information im IRP aktualisieren, um auf die aktualisierte Liste zu zeigen, und den Puffer frei geben, der die ursprüngliche Liste enthält.)

Die FilterResources-Funktion gibt TRUE zurück (wahrscheinlich aus der switch-Anweisung , obwohl die Details zur Vereinfachung des Codebeispiels weggelassen werden), wenn sie die Ressource findet, nach der sie in der Liste sucht, oder wenn sie eine Änderung an der Liste vornimmt, die die Größe der Liste nicht ändert. Andernfalls wird FALSE zurückgegeben.

/* Modify the resource list in place (without changing its size). */

BOOLEAN FilterResources(PIO_RESOURCE_REQUIREMENTS_LIST reqlist)
{
    PIO_RESOURCE_LIST list;

    list = reqlist->List;

    for (int ix = 0; ix < reqlist->AlternativeLists; ++ix)
    {
        /* Process resources in IO_RESOURCE_LIST block number ix. */

        for (int jx = 0; jx < list->Count; ++jx)
        {
            PIO_RESOURCE_DESCRIPTOR desc; 

            desc = list->Descriptors + jx;

            switch (desc->Type)
            {
               /* Process element jx in Descriptors array. */

               ...

            }
        }

        /* Advance to next IO_RESOURCE_LIST block in memory. */

        list = (PIO_RESOURCE_LIST)(list->Descriptors + list->Count);
    }

    return FALSE;
}