WdfCmResourceListInsertDescriptor 함수(wdfresource.h)

아티클
08/08/2023

[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

List가 지정하는 논리 구성의 인덱스로 사용되는 0부터 시작하는 값입니다. 리소스 목록의 끝에 리소스 설명자를 추가하려면 WdfCmResourceListGetCount에서 WDF_INSERT_AT_END 또는 반환 값을 지정합니다.

반환 값

WdfCmResourceListInsertDescriptor 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 지정되었습니다.
STATUS_ACCESS_DENIED	드라이버가 List 매개 변수가 지정한 논리적 구성에 설명자를 추가할 수 없습니다. 예를 들어 드라이버는 EvtDevicePrepareHardware 또는 EvtDeviceReleaseHardware 콜백 함수가 수신한 논리적 구성을 수정할 수 없습니다.
STATUS_INSUFFICIENT_RESOURCES	프레임워크에서 설명자 매개 변수가 가리키는 설명자를 저장할 공간을 할당할 수 없습니다.
STATUS_ARRAY_BOUNDS_EXCEEDED	Index 매개 변수가 지정한 값이 너무 큽니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 시스템 버그 검사 발생합니다.

설명

WdfCmResourceListInsertDescriptor 메서드는 Index 값이 식별하는 리소스 설명자 앞에 설명자가 지정하는 리소스 설명자를 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)