Funzione WdfCmResourceListInsertDescriptor (wdfresource.h)

Articolo
02/07/2025

[Si applica solo a KMDF]

Il metodo WdfCmResourceListInsertDescriptor inserisce un descrittore di risorsa 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 per un oggetto elenco di risorse 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 List. Per aggiungere un descrittore di risorsa 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 è autorizzato ad aggiungere descrittori alla configurazione logica specificata dal parametro list. Ad esempio, il driver non è riuscito a modificare la configurazione logica ricevuta EvtDevicePrepareHardware o EvtDeviceReleaseHardware funzione di callback.
STATUS_INSUFFICIENT_RESOURCES	Il framework non è riuscito ad allocare spazio per archiviare il descrittore a cui punta il descrittore descrittore parametro.
STATUS_ARRAY_BOUNDS_EXCEEDED	Il valore specificato dal parametro index è troppo grande.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo dei bug di sistema.

Osservazioni

Il metodo WdfCmResourceListInsertDescriptor inserisce il descrittore di risorsa che descrittore specifica nell'elenco di risorse specificato List, davanti al descrittore di risorsa identificato valore di 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 driver Framework-Based.

Esempi

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

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
                                               );
...

}

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
intestazione	wdfresource.h (include Wdf.h)
libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	<=DISPATCH_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)