Función WdfCmResourceListInsertDescriptor (wdfresource.h)

Artículo
08/08/2023

[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 especifica List . 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	El controlador no pudo agregar 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 recibió su función de devolución de llamada EvtDevicePrepareHardware o EvtDeviceReleaseHardware .
STATUS_INSUFFICIENT_RESOURCES	El marco de trabajo no pudo asignar espacio para almacenar el descriptor al que apunta el parámetro Descriptor .
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.

Comentarios

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 identifica el valor de Índice .

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 de índice . Como alternativa, use el método WdfCmResourceListAppendDescriptor .

El marco copia el contenido de la estructura de 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfresource.h (incluya Wdf.h)
Library	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)