WdfUsbTargetDeviceRetrieveConfigDescriptor 함수(wdfusb.h)
[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 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
지정된 대상에 대해 구성 설명자를 사용할 수 없습니다. |
|
잘못된 매개 변수가 감지되었습니다. |
|
지정된 버퍼 크기가 데이터에 비해 너무 작거나 호출자가 ConfigDescriptor 매개 변수에 대해 NULL을 제공했습니다. |
이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.
드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.
설명
WdfUsbTargetDeviceRetrieveConfigDescriptor 메서드는 지정된 USB 디바이스의 모든 구성 정보(즉, 구성 설명자와 있을 수 있는 모든 인터페이스 또는 엔드포인트 설명자)를 검색합니다. 이 정보의 형식에 대해 알아보려면 USB 사양을 참조하세요.
WdfUsbTargetDeviceSelectConfig를 사용하여 설명자 목록에 나열된 첫 번째 USB 구성만 선택할 수 있지만 이 단일 구성 내에서 여러 인터페이스를 선택할 수 있습니다.
드라이버는 다음과 같이 WdfUsbTargetDeviceRetrieveConfigDescriptor를 두 번 호출해야 합니다.
- ConfigDescriptor 포인터를 NULL로 설정하여 WdfUsbTargetDeviceRetrieveConfigDescriptor가 ConfigDescriptorLength가 가리키는 주소에서 필요한 버퍼 크기를 반환하도록 합니다.
- 구성 정보를 저장할 버퍼 공간을 할당합니다. 예를 들어 드라이버는 ExAllocatePoolWithTag 를 호출하여 버퍼를 할당하거나 WdfMemoryCreate 를 호출하여 프레임워크 메모리 개체를 만들 수 있습니다.
- WdfUsbTargetDeviceRetrieveConfigDescriptor를 다시 호출하여 새 버퍼 및 버퍼 크기에 대한 포인터를 전달합니다.
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) |