Função WdfCmResourceListInsertDescriptor (wdfresource.h)

Artigo
02/07/2025

[Aplica-se somente ao KMDF]

O método WdfCmResourceListInsertDescriptor insere um descritor de recursos em uma lista de recursos especificada.

Sintaxe

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

Parâmetros

[in] List

Um identificador para um objeto de lista de recursos da estrutura que representa uma lista de recursos de hardware para um dispositivo.

[in] Descriptor

Um ponteiro para uma estrutura CM_PARTIAL_RESOURCE_DESCRIPTOR que descreve um recurso de hardware.

[in] Index

Um valor baseado em zero usado como um índice na configuração lógica especificada List. Para adicionar um descritor de recursos ao final da lista de recursos, especifique WDF_INSERT_AT_END ou o valor retornado de WdfCmResourceListGetCount.

Valor de retorno

WdfCmResourceListInsertDescriptor retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_ACCESS_DENIED	O driver não tinha permissão para adicionar descritores à configuração lógica especificada pelo parâmetro List. Por exemplo, o driver não pôde modificar a configuração lógica que seu EvtDevicePrepareHardware ou EvtDeviceReleaseHardware função de retorno de chamada recebeu.
STATUS_INSUFFICIENT_RESOURCES	A estrutura não pôde alocar espaço para armazenar o descritor ao qual o descritor de aponta.
STATUS_ARRAY_BOUNDS_EXCEEDED	O valor que o parâmetro índice especificado era muito grande.

Uma verificação de bugs do sistema ocorre se o driver fornece um identificador de objeto inválido.

Observações

O método WdfCmResourceListInsertDescriptor insere o descritor de recursos que Descritor especifica na lista de recursos que List especifica, na frente do descritor de recursos que índice valor identifica.

Para adicionar um descritor de recursos ao final de uma lista de recursos, especifique WDF_INSERT_AT_END ou o valor retornado de WdfCmResourceListGetCount como o valor índice. Como alternativa, use o método WdfCmResourceListAppendDescriptor.

A estrutura copia o conteúdo da estrutura CM_PARTIAL_RESOURCE_DESCRIPTOR no armazenamento interno, de modo que a rotina de driver que chama WdfCmResourceListInsertDescriptor pode alocar a estrutura localmente. Depois que o driver chama WdfCmResourceListInsertDescriptor, ele pode reutilizar a estrutura CM_PARTIAL_RESOURCE_DESCRIPTOR.

Para obter mais informações sobre listas de recursos, consulte Recursos de Hardware para drivers de Framework-Based.

Exemplos

O exemplo de código a seguir adiciona um descritor de recursos ao final da lista de recursos que um evtDeviceResourcesQuery função de retorno de chamada recebe.

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
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
cabeçalho	wdfresource.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (consulte o Controle de Versão da Biblioteca da Estrutura.)
IRQL	<=DISPATCH_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também

CM_PARTIAL_RESOURCE_DESCRIPTOR

EvtDevicePrepareHardware

EvtDeviceReleaseHardware

EvtDeviceResourcesQuery

WdfCmResourceListAppendDescriptor

Compartilhar via