WdfUsbTargetDeviceRetrieveConfigDescriptor 함수(wdfusb.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfUsbTargetDeviceRetrieveConfigDescriptor 메서드는 지정된 프레임워크 USB 디바이스 개체와 연결된 USB 디바이스에 대한 USB 구성 설명자를 검색합니다.

구문

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

매개 변수

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParameters에 대한 이전 호출에서 가져온 USB 디바이스 개체에 대한 핸들입니다.

[out] ConfigDescriptor

USB_CONFIGURATION_DESCRIPTOR 구조를 수신하고 하나 이상의 USB_INTERFACE_DESCRIPTOR 및 USB_ENDPOINT_DESCRIPTOR 구조체를 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 경우 WdfUsbTargetDeviceRetrieveConfigDescriptor 는 필요한 버퍼 길이를 반환합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in, out] ConfigDescriptorLength

ConfigDescriptor가 가리키는 버퍼의 길이를 제공하는 위치에 대한 포인터입니다. ConfigDescriptor에 제공된 포인터가 NULL이면 WdfUsbTargetDeviceRetrieveConfigDescriptor는 ConfigDescriptorLength가 가리키는 위치에 필요한 버퍼 길이를 반환합니다.

반환 값

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

반환 코드	설명
STATUS_INVALID_DEVICE_STATE	지정된 대상에 대해 구성 설명자를 사용할 수 없습니다.
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 감지되었습니다.
STATUS_BUFFER_TOO_SMALL	지정된 버퍼 크기가 데이터에 비해 너무 작거나 호출자가 ConfigDescriptor 매개 변수에 대해 NULL을 제공했습니다.

이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.

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

설명

WdfUsbTargetDeviceRetrieveConfigDescriptor 메서드는 지정된 USB 디바이스의 모든 구성 정보(즉, 구성 설명자와 있을 수 있는 모든 인터페이스 또는 엔드포인트 설명자)를 검색합니다. 이 정보의 형식에 대해 알아보려면 USB 사양을 참조하세요.

WdfUsbTargetDeviceSelectConfig를 사용하여 설명자 목록에 나열된 첫 번째 USB 구성만 선택할 수 있지만 이 단일 구성 내에서 여러 인터페이스를 선택할 수 있습니다.

드라이버는 다음과 같이 WdfUsbTargetDeviceRetrieveConfigDescriptor를 두 번 호출해야 합니다.

ConfigDescriptor 포인터를 NULL로 설정하여 WdfUsbTargetDeviceRetrieveConfigDescriptor가 ConfigDescriptorLength가 가리키는 주소에서 필요한 버퍼 크기를 반환하도록 합니다.
구성 정보를 저장할 버퍼 공간을 할당합니다. 예를 들어 드라이버는 ExAllocatePoolWithTag 를 호출하여 버퍼를 할당하거나 WdfMemoryCreate 를 호출하여 프레임워크 메모리 개체를 만들 수 있습니다.
WdfUsbTargetDeviceRetrieveConfigDescriptor를 다시 호출하여 새 버퍼 및 버퍼 크기에 대한 포인터를 전달합니다.

WdfUsbTargetDeviceRetrieveConfigDescriptor에 대한 두 번째 호출이 반환된 후 ConfigDescriptor가 가리키는 버퍼에는 USB_CONFIGURATION_DESCRIPTOR 구조체와 하나 이상의 USB_INTERFACE_DESCRIPTOR 및 USB_ENDPOINT_DESCRIPTOR 구조가 포함됩니다. 이러한 후자의 구조는 USB 사양에 설명된 순서대로 정렬됩니다.

WdfUsbTargetDeviceRetrieveConfigDescriptor 메서드 및 USB I/O 대상에 대한 자세한 내용은 USB I/O 대상을 참조하세요.

예제

다음 코드 예제 에서는 WdfUsbTargetDeviceRetrieveConfigDescriptor 를 호출하여 필요한 버퍼 크기를 가져오고, WdfMemoryCreate 를 호출하여 메모리 개체 및 버퍼를 만든 다음, WdfUsbTargetDeviceRetrieveConfigDescriptor 를 다시 호출하여 디바이스의 구성 정보를 가져옵니다.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfusb.h(Wdfusb.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)