IO_RESOURCE_REQUIREMENTS_LIST structure (miniport.h)

Article
03/08/2023

La structure IO_RESOURCE_REQUIREMENTS_LIST décrit des ensembles de configurations de ressources qui peuvent être utilisées 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 de base zéro affecté 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 (ou configurations) alternatives de ressources matérielles décrites par cette structure IO_RESOURCE_REQUIREMENTS_LIST . Le membre List est l’en-tête de la première liste alternative.

List[1]

Le IO_RESOURCE_LIST structure qui sert d’en-tête pour la première autre liste de ressources matérielles. Si la structure IO_RESOURCE_REQUIREMENTS_LIST décrit plusieurs listes alternatives, la deuxième liste de remplacement 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’elle contient. Pour plus d'informations, consultez la section Notes qui suit.

Remarques

Cette structure est utilisée par les IRP_MN_FILTER_RESOURCE_REQUIREMENTS et IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRP 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 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 à l’autre. Le code du pilote peut utiliser l’arithmétique du pointeur pour passer d’une autre liste à la suivante. Par exemple, si un paramètre nommé list est un pointeur vers la structure IO_RESOURCE_LIST au début d’une autre liste, la liste peut être mise à 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 est le nombre d’éléments dans le 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 , il guide généralement la liste des ressources vers laquelle pointe 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 exigences en matière de ressources dans 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) si elle 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;
}