WdfUsbTargetDeviceAllocAndQueryString 함수(wdfusb.h)

아티클
02/27/2024

[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)