struttura IO_RESOURCE_REQUIREMENTS_LIST (wdm.h)

Articolo
02/27/2024

La struttura IO_RESOURCE_REQUIREMENTS_LIST descrive i set di configurazioni delle risorse che possono essere usate da un dispositivo. Ogni configurazione rappresenta una gamma di risorse non elaborate, di vari tipi, che possono essere usate da un dispositivo.

Sintassi

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;

Members

ListSize

Numero totale di byte che costituiscono la struttura IO_RESOURCE_REQUIREMENTS_LIST , la relativa matrice IO_RESOURCE_LIST e la matrice di IO_RESOURCE_DESCRIPTOR del secondo.

InterfaceType

Specifica un tipo di interfaccia. Deve essere uno dei tipi definiti da INTERFACE_TYPE, in Wdm.h o Ntddk.h. Non usato dai driver WDM.

BusNumber

Numero di bus a base zero assegnato dal sistema. Non usato dai driver WDM.

SlotNumber

Numero di slot di sistema. Non usato dai driver WDM.

Reserved[3]

Riservato.

AlternativeLists

Numero di elenchi alternativi (o configurazioni) di risorse hardware descritte da questa struttura IO_RESOURCE_REQUIREMENTS_LIST . Il membro List è l'intestazione per il primo elenco alternativo.

List[1]

Struttura IO_RESOURCE_LIST che funge da intestazione per il primo elenco alternativo di risorse hardware. Se la struttura IO_RESOURCE_REQUIREMENTS_LIST descrive più elenchi alternativi, il secondo elenco alternativo segue immediatamente il primo elenco alternativo in memoria e così via. Le dimensioni di ogni elenco alternativo dipendono dalla lunghezza della matrice IO_RESOURCE_DESCRIPTOR che contiene. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Commenti

Questa struttura viene usata dai provider di integrazione IRP_MN_FILTER_RESOURCE_REQUIREMENTS e IRP_MN_QUERY_RESOURCE_REQUIREMENTS per descrivere una o più configurazioni alternative delle risorse hardware.

La struttura IO_RESOURCE_REQUIREMENTS_LIST è un'intestazione per una struttura di dati più grande, di dimensioni variabili, che specifica uno o più elenchi alternativi di risorse. Tutti i dati in questa struttura più grande occupano un blocco contiguo di memoria, le cui dimensioni sono specificate dal membro ListSize . Ogni elenco alternativo occupa un blocco secondario all'interno del blocco più grande.

Ogni elenco alternativo inizia con una struttura IO_RESOURCE_LIST , che funge da intestazione per una matrice di strutture IO_RESOURCE_DESCRIPTOR . La lunghezza di questa matrice determina le dimensioni dell'elenco, che può variare da un elenco alternativo al successivo. Il codice del driver può usare l'aritmetica del puntatore per passare da un elenco alternativo al successivo. Ad esempio, se un parametro denominato list è un puntatore alla struttura IO_RESOURCE_LIST all'inizio di un elenco alternativo, è possibile aggiornare l'elenco in modo che punti all'inizio dell'elenco successivo come indicato di seguito:

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

In questo esempio è list->Descriptors un puntatore all'inizio della matrice IO_RESOURCE_DESCRIPTOR ed list->Count è il numero di elementi nella matrice. Per altre informazioni sui membri Descriptor e Count , vedere IO_RESOURCE_LIST.

Esempio

Se un driver contiene un gestore per un IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP, il gestore esegue in genere l'elenco di risorse a cui punta il campo IoStatus.Information in IRP. L'esempio di codice seguente contiene una funzione denominata FilterResources, chiamata nel gestore per la procedura dettagliata dell'elenco. Questa funzione verifica che una determinata risorsa sia specificata nell'elenco o modifichi i requisiti delle risorse nell'elenco senza modificare le dimensioni dell'elenco. Una funzione che modifica le dimensioni dell'elenco deve allocare un buffer per l'elenco aggiornato, scrivere l'elenco nel buffer, aggiornare il campo IoStatus.Information in IRP in modo che punti all'elenco aggiornato e liberare il buffer che contiene l'elenco originale.

La funzione FilterResources restituisce TRUE (probabilmente dall'istruzione switch , anche se i dettagli vengono omessi per semplificare l'esempio di codice) se trova la risorsa che sta cercando nell'elenco o se apporta una modifica all'elenco che non modifica le dimensioni dell'elenco. In caso contrario, restituisce 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;
}