Функция WdfCmResourceListInsertDescriptor (wdfresource.h)

Статья
02/07/2025

[Применимо только к KMDF]

Метод WdfCmResourceListInsertDescriptor вставляет дескриптор ресурса в указанный список ресурсов.

Синтаксис

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

Параметры

[in] List

Дескриптор объекта списка ресурсов платформы, представляющий список аппаратных ресурсов для устройства.

[in] Descriptor

Указатель на структуру CM_PARTIAL_RESOURCE_DESCRIPTOR, описывающую аппаратный ресурс.

[in] Index

Отсчитываемое от нуля значение, используемое в качестве индекса в логическую конфигурацию, которая указана списка. Чтобы добавить дескриптор ресурса в конец списка ресурсов, укажите WDF_INSERT_AT_END или возвращаемое значение из WdfCmResourceListGetCount.

Возвращаемое значение

WdfCmResourceListInsertDescriptor возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Указан недопустимый параметр.
STATUS_ACCESS_DENIED	Драйверу не разрешено добавлять дескрипторы в логическую конфигурацию, указанную параметром списка. Например, драйвер не мог изменить логическую конфигурацию, полученную EvtDevicePrepareHardware или EvtDeviceReleaseHardware функцию обратного вызова.
STATUS_INSUFFICIENT_RESOURCES	Платформа не могла выделить место для хранения дескриптора, на который указывает дескриптор.
STATUS_ARRAY_BOUNDS_EXCEEDED	Значение, указанное параметром индекса, было слишком большим.

Проверка системной ошибки возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Метод WdfCmResourceListInsertDescriptor вставляет дескриптор ресурса, который дескриптор указывает в список ресурсов, который List указывает перед дескриптором ресурса, который значение индекса.

Чтобы добавить дескриптор ресурса в конец списка ресурсов, укажите WDF_INSERT_AT_END или возвращаемое значение из WdfCmResourceListGetCount в качестве значения индекса. Кроме того, используйте метод WdfCmResourceListAppendDescriptor.

Платформа копирует содержимое структуры CM_PARTIAL_RESOURCE_DESCRIPTOR в внутреннее хранилище, поэтому подпрограмма драйвера, которая вызывает WdfCmResourceListInsertDescriptor может выделить структуру локально. После вызова драйвера WdfCmResourceListInsertDescriptorон может повторно использовать структуру CM_PARTIAL_RESOURCE_DESCRIPTOR.

Дополнительные сведения о списках ресурсов см. в разделе Аппаратные ресурсы для Framework-Based драйверов.

Примеры

Следующий пример кода добавляет дескриптор ресурса в конец списка ресурсов, который получает функция обратного вызова 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
                                               );
...

}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
заголовка	wdfresource.h (включая Wdf.h)
библиотеки	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	<=DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)