Función WdfCmResourceListInsertDescriptor (wdfresource.h)

Artículo
02/07/2025

[Solo se aplica a KMDF]

El método WdfCmResourceListInsertDescriptor inserta un descriptor de recursos en una lista de recursos especificada.

Sintaxis

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

Parámetros

[in] List

Identificador de un objeto de lista de recursos de marco que representa una lista de recursos de hardware para un dispositivo.

[in] Descriptor

Puntero a una estructura de CM_PARTIAL_RESOURCE_DESCRIPTOR que describe un recurso de hardware.

[in] Index

Valor de base cero que se usa como índice en la configuración lógica que List especifica. Para agregar un descriptor de recursos al final de la lista de recursos, especifique WDF_INSERT_AT_END o el valor devuelto de WdfCmResourceListGetCount.

Valor devuelto

WdfCmResourceListInsertDescriptor devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se especificó un parámetro no válido.
STATUS_ACCESS_DENIED	No se permitió que el controlador agregue descriptores a la configuración lógica que especificó el parámetro list . Por ejemplo, el controlador no pudo modificar la configuración lógica que su EvtDevicePrepareHardware o EvtDeviceReleaseHardware función de devolución de llamada recibida.
STATUS_INSUFFICIENT_RESOURCES	El marco no pudo asignar espacio para almacenar el descriptor al que apunta el descriptor parámetro.
STATUS_ARRAY_BOUNDS_EXCEEDED	El valor que especificó el parámetro index era demasiado grande.

Se produce una comprobación de errores del sistema si el controlador proporciona un identificador de objeto no válido.

Observaciones

El método WdfCmResourceListInsertDescriptor inserta el descriptor de recursos que Descriptor especifica en la lista de recursos que List especifica, delante del descriptor de recursos que index valor.

Para agregar un descriptor de recursos al final de una lista de recursos, especifique WDF_INSERT_AT_END o el valor devuelto de WdfCmResourceListGetCount como valor index de. Como alternativa, use el método WdfCmResourceListAppendDescriptor.

El marco copia el contenido de la estructura CM_PARTIAL_RESOURCE_DESCRIPTOR en el almacenamiento interno, por lo que la rutina del controlador que llama a WdfCmResourceListInsertDescriptor puede asignar la estructura localmente. Una vez que el controlador llama a WdfCmResourceListInsertDescriptor, puede reutilizar la estructura de CM_PARTIAL_RESOURCE_DESCRIPTOR.

Para obtener más información sobre las listas de recursos, consulte Recursos de hardware para controladores de Framework-Based.

Ejemplos

En el ejemplo de código siguiente se agrega un descriptor de recursos al final de la lista de recursos que recibe una función de devolución de llamada 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
                                               );
...

}

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
encabezado de	wdfresource.h (incluya Wdf.h)
biblioteca de	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
irQL	<=DISPATCH_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)