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_INTERFACE_DESCRIPTOR 및 USB_ENDPOINT_DESCRIPTOR 구조 뒤에 USB_CONFIGURATION_DESCRIPTOR 구조를 수신하는 호출자 할당 버퍼에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL 수 있습니다. 이 경우 WdfUsbTargetDeviceRetrieveConfigDescriptor 필요한 버퍼 길이를 반환합니다. 자세한 내용은 다음 설명 섹션을 참조하세요.
[in, out] ConfigDescriptorLength
ConfigDescriptor 가리키는 버퍼의 길이를 제공하는 위치에 대한 포인터입니다. ConfigDescriptor 제공된 포인터가 NULL 경우 WdfUsbTargetDeviceRetrieveConfigDescriptorConfigDescriptorLength가리키는 위치에서 필요한 버퍼 길이를 반환합니다.
반환 값
WdfUsbTargetDeviceRetrieveConfigDescriptor 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
반환 코드 | 묘사 |
---|---|
|
지정된 대상에 대해 구성 설명자를 사용할 수 없습니다. |
|
잘못된 매개 변수가 검색되었습니다. |
|
지정된 버퍼 크기가 데이터에 비해 너무 작거나 ConfigDescriptor 매개 변수에 NULL 제공된 호출자입니다. |
이 메서드는 다른NTSTATUS 값을 반환할 수도 있습니다.
드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.
발언
WdfUsbTargetDeviceRetrieveConfigDescriptor 메서드는 지정된 USB 디바이스의 모든 구성 정보(즉, 구성 설명자와 있을 수 있는 모든 인터페이스 또는 엔드포인트 설명자)를 검색합니다. 이 정보의 형식에 대한 자세한 내용은 USB 사양을 참조하세요.
WdfUsbTargetDeviceSelectConfig 사용하여 설명자 목록에 나열된 첫 번째 USB 구성만 선택할 수 있지만 이 단일 구성 내에서 여러 인터페이스를 선택할 수 있습니다.
드라이버는 다음과 같이 WdfUsbTargetDeviceRetrieveConfigDescriptor 두 번 호출해야 합니다.
- ConfigDescriptor 포인터를 NULL설정하여 WdfUsbTargetDeviceRetrieveConfigDescriptorConfigDescriptorLength가 가리키는 주소에서 필요한 버퍼 크기를 반환하도록.
- 구성 정보를 저장할 버퍼 공간을 할당합니다. 예를 들어 드라이버는 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) |