WdfUsbTargetDeviceAllocAndQueryString 함수(wdfusb.h)

아티클
02/07/2025

[KMDF 및 UMDF에 적용]

WdfUsbTargetDeviceAllocAndQueryString 메서드는 버퍼를 할당한 다음 지정된 USB 디바이스 및 설명자 인덱스 값과 연결된 유니코드 문자열을 검색합니다.

통사론

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] PUSHORT                NumCharacters,
  [in]            UCHAR                  StringIndex,
  [in, optional]  USHORT                 LangID
);

매개 변수

[in] UsbDevice

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

[in, optional] StringMemoryAttributes

새 메모리 개체에 대한 호출자 제공 특성을 포함하는 호출자가 할당한 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.

[out] StringMemory

유니코드 문자열을 포함하는 메모리 개체에 대한 핸들을 받는 위치에 대한 포인터입니다. 이 문자열은 디바이스에서 NULL로 종료된 문자열을 제공하는 경우에만 NULL로 종료됩니다.

[out, optional] NumCharacters

문자열 설명자에 포함된 문자 수를 받는 위치에 대한 포인터입니다. 유니코드 문자열이 NULL로 끝나는 경우 이 숫자에는 NULL 문자가 포함됩니다. 이 매개 변수는 선택 사항이며 NULL 수 있습니다.

[in] StringIndex

유니코드 문자열을 식별하는 인덱스 값입니다. 이 인덱스 값은 USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR또는 USB_INTERFACE_DESCRIPTOR 구조체에서 가져옵니다.

[in, optional] LangID

언어 식별자입니다. 유니코드 문자열은 이 식별자가 지정하는 언어에 대해 검색됩니다. 디바이스의 지원되는 언어 식별자를 가져오는 방법에 대한 자세한 내용은 USB 사양을 참조하세요.

반환 값

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

반환 코드	묘사
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 검색되었습니다.
STATUS_INSUFFICIENT_RESOURCES	메모리 버퍼를 할당할 수 없습니다.
STATUS_DEVICE_DATA_ERROR	USB 디바이스가 잘못된 설명자를 반환했습니다.
STATUS_BUFFER_OVERFLOW	제공된 버퍼가 너무 작습니다.

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

드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.

발언

문자열 설명자를 가져오기 위해 드라이버가 한 번만 호출해야 하는 WdfUsbTargetDeviceAllocAndQueryString 메서드는 문자열을 가져오기 위해 두 번 호출해야 하는 WdfUsbTargetDeviceQueryString 메서드의 대안입니다.

이 메서드는 지정된 USB 문자열 설명자를 찾고, 설명자에서 메모리 개체로 유니코드 문자열을 복사하고, 메모리 개체에 대한 핸들을 반환합니다.

WdfUsbTargetDeviceAllocAndQueryString호출한 후 드라이버는 StringMemory 핸들을 WdfMemoryGetBuffer 전달하여 메모리 개체의 내용에 액세스할 수 있습니다.

USB 문자열 설명자에 대한 자세한 내용은 USB 사양을 참조하세요.

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

예제

다음 코드 예제에서는 WdfUsbTargetDeviceAllocAndQueryString 호출하여 USB 디바이스 설명자에서 제조업체의 이름 문자열(0x0409)을 가져옵니다. (드라이버는 이전에 드라이버 정의 컨텍스트 공간에 설명자를 저장했습니다.)

PMY_DEVICE_CONTEXT  myDeviceContext;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &numCharacters,
                                        myDeviceContext->UsbDeviceDescr.iManufacturer,
                                        0x0409
                                        );

요구 사항

요구	값
대상 플랫폼	보편적
최소 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)