structure IO_RESOURCE_REQUIREMENTS_LIST (miniport.h)

Article
02/07/2025

La structure IO_RESOURCE_REQUIREMENTS_LIST décrit les ensembles de configurations de ressources qui peuvent être utilisés par un appareil. Chaque configuration représente une plage de ressources brutes, de différents types, qui peuvent être utilisées par un appareil.

Syntaxe

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;

Membres

ListSize

Nombre total d’octets qui constituent la structure IO_RESOURCE_REQUIREMENTS_LIST, son tableau IO_RESOURCE_LIST et le tableau IO_RESOURCE_DESCRIPTOR de ce dernier.

InterfaceType

Spécifie un type d’interface. Il doit s’agir de l’un des types définis par INTERFACE_TYPE, dans Wdm.h ou Ntddk.h. (Non utilisé par les pilotes WDM.)

BusNumber

Numéro de bus basé sur zéro attribué par le système. (Non utilisé par les pilotes WDM.)

SlotNumber

Numéro d’emplacement système. (Non utilisé par les pilotes WDM.)

Reserved[3]

Non utilisé.

AlternativeLists

Nombre de listes alternatives (ou configurations) de ressources matérielles décrites par cette structure IO_RESOURCE_REQUIREMENTS_LIST. Le membre Liste est l’en-tête de la première liste alternative.

List[1]

Structure IO_RESOURCE_LIST qui sert d’en-tête pour la première liste alternative de ressources matérielles. Si la structure IO_RESOURCE_REQUIREMENTS_LIST décrit plusieurs listes alternatives, la deuxième liste alternative suit immédiatement la première liste alternative en mémoire, et ainsi de suite. La taille de chaque liste alternative dépend de la longueur du tableau IO_RESOURCE_DESCRIPTOR qu’il contient. Pour plus d’informations, consultez la section Remarques suivante.

Remarques

Cette structure est utilisée par les IRP_MN_FILTER_RESOURCE_REQUIREMENTS et les IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRPs pour décrire une ou plusieurs configurations alternatives de ressources matérielles .

La structure IO_RESOURCE_REQUIREMENTS_LIST est un en-tête pour une structure de données plus grande, de taille variable, qui spécifie une ou plusieurs listes alternatives de ressources. Toutes les données de cette structure plus grande occupent un bloc de mémoire contigu, dont la taille est spécifiée par le membre ListSize. Chaque liste alternative occupe un sous-bloc dans le bloc le plus grand.

Chaque liste alternative commence par une structure IO_RESOURCE_LIST, qui sert d’en-tête pour un tableau de structures IO_RESOURCE_DESCRIPTOR. La longueur de ce tableau détermine la taille de la liste, qui peut varier d’une autre liste à la suivante. Le code du pilote peut utiliser l’arithmétique du pointeur pour passer d’une liste alternative à la suivante. Par exemple, si un paramètre nommé liste est un pointeur vers la structure IO_RESOURCE_LIST au début d’une liste alternative, liste peut être mis à jour pour pointer vers le début de la liste suivante comme suit :

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

Dans cet exemple, list->Descriptors est un pointeur vers le début du tableau IO_RESOURCE_DESCRIPTOR et list->Count correspond au nombre d’éléments du tableau. Pour plus d’informations sur les descripteurs et les membres Count, consultez IO_RESOURCE_LIST.

Exemples

Si un pilote contient un gestionnaire pour un IRP IRP_MN_FILTER_RESOURCE_REQUIREMENTS, le gestionnaire guide généralement la liste des ressources pointée par le champ IoStatus.Information dans l’IRP. L’exemple de code suivant contient une fonction nommée FilterResources, appelée dans le gestionnaire pour parcourir la liste. Cette fonction vérifie qu’une ressource particulière est spécifiée dans la liste ou modifie les besoins en ressources de la liste sans modifier la taille de la liste. (Une fonction qui modifie la taille de la liste doit allouer une mémoire tampon pour la liste mise à jour, écrire la liste dans cette mémoire tampon, mettre à jour le champ IoStatus.Information dans l’IRP pour pointer vers la liste mise à jour et libérer la mémoire tampon qui contient la liste d’origine.)

La fonction FilterResources retourne TRUE (probablement à partir de l’instruction switch, bien que les détails soient omis pour simplifier l’exemple de code) s’il trouve la ressource qu’elle recherche dans la liste, ou si elle apporte une modification à la liste qui ne modifie pas la taille de la liste. Sinon, elle retourne FALSE.

/* 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;
}