Funzione WdfCmResourceListInsertDescriptor (wdfresource.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

Il metodo WdfCmResourceListInsertDescriptor inserisce un descrittore di risorse in un elenco di risorse specificato.

Sintassi

NTSTATUS WdfCmResourceListInsertDescriptor(
  [in] WDFCMRESLIST                    List,
  [in] PCM_PARTIAL_RESOURCE_DESCRIPTOR Descriptor,
  [in] ULONG                           Index
);

Parametri

[in] List

Handle a un oggetto resource-list framework che rappresenta un elenco di risorse hardware per un dispositivo.

[in] Descriptor

Puntatore a una struttura CM_PARTIAL_RESOURCE_DESCRIPTOR che descrive una risorsa hardware.

[in] Index

Valore in base zero utilizzato come indice nella configurazione logica specificata da List . Per aggiungere un descrittore di risorse alla fine dell'elenco di risorse, specificare WDF_INSERT_AT_END o il valore restituito da WdfCmResourceListGetCount.

Valore restituito

WdfCmResourceListInsertDescriptor restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_ACCESS_DENIED	Il driver non è stato autorizzato ad aggiungere descrittori alla configurazione logica specificata dal parametro List . Ad esempio, il driver non è riuscito a modificare la configurazione logica ricevuta dalla funzione di callback EvtDevicePrepareHardware o EvtDeviceReleaseHardware .
STATUS_INSUFFICIENT_RESOURCES	Il framework non ha potuto allocare spazio per archiviare il descrittore a cui punta il parametro Descrittore .
STATUS_ARRAY_BOUNDS_EXCEEDED	Valore specificato dal parametro Index troppo grande.

Un controllo del bug di sistema si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Il metodo WdfCmResourceListInsertDescriptor inserisce il descrittore di risorsa che Descriptor specifica nell'elenco di risorse specificato da List , davanti al descrittore di risorsa identificato dal valore Index .

Per aggiungere un descrittore di risorsa alla fine di un elenco di risorse, specificare WDF_INSERT_AT_END o il valore restituito da WdfCmResourceListGetCount come valore index . In alternativa, usare il metodo WdfCmResourceListAppendDescriptor .

Il framework copia il contenuto della struttura CM_PARTIAL_RESOURCE_DESCRIPTOR nell'archiviazione interna, quindi la routine del driver che chiama WdfCmResourceListInsertDescriptor può allocare la struttura in locale. Dopo che il driver chiama WdfCmResourceListInsertDescriptor, può riutilizzare la struttura CM_PARTIAL_RESOURCE_DESCRIPTOR.

Per altre informazioni sugli elenchi di risorse, vedere Risorse hardware per i driver di Framework-Based.

Esempio

Nell'esempio di codice seguente viene aggiunto un descrittore di risorsa alla fine dell'elenco di risorse ricevuto da una funzione di callback EvtDeviceResourcesQuery .

NTSTATUS
PdoEvtDeviceResourcesQuery(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  Resources
    )
{
    CM_PARTIAL_RESOURCE_DESCRIPTOR newDescriptor;
...
    newDescriptor.Type = CmResourceTypePort;
    newDescriptor.ShareDisposition = CmResourceShareDeviceExclusive;
    newDescriptor.Flags = CM_RESOURCE_PORT_IO|CM_RESOURCE_PORT_16_BIT_DECODE;
    newDescriptor.u.Port.Length = 1;
    newDescriptor.u.Port.Start = 0;

    status = WdfCmResourceListInsertDescriptor(
                                               Resources,
                                               &newDescriptor,
                                               WDF_INSERT_AT_END
                                               );
...

}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfresource.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)