WdfUsbTargetDeviceQueryString 함수(wdfusb.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfUsbTargetDeviceQueryString 메서드는 지정된 USB 디바이스 및 설명자 인덱스 값과 연결된 유니코드 문자열을 검색합니다.

구문

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       PUSHORT                   NumCharacters,
  [in]            UCHAR                     StringIndex,
  [in, optional]  USHORT                    LangID
);

매개 변수

[in] UsbDevice

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

[in, optional] Request

프레임워크 요청 개체에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in, optional] RequestOptions

요청에 대한 옵션을 지정하는 호출자가 할당한 WDF_REQUEST_SEND_OPTIONS 구조체에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[out, optional] String

요청된 유니코드 문자열을 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다. 이 문자열은 디바이스가 NULL로 끝나는 문자열을 제공하는 경우에만 NULL로 종료됩니다. 이 포인터가 NULL이면 WdfUsbTargetDeviceQueryString 은 NumCharacters 가 가리키는 위치에 필요한 버퍼 크기(즉, 필요한 유니코드 문자 수)를 반환합니다.

[in, out] NumCharacters

호출자가 할당한 변수에 대한 포인터입니다. 호출자는 버퍼가 보유할 수 있는 유니코드 문자 수를 제공합니다. WdfUsbTargetDeviceQueryString이 반환되면 변수는 문자열 버퍼가 수신하는 유니코드 문자열에 있는 문자 수(제공된 경우 NULL 종결자 포함)를 받습니다.

[in] StringIndex

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

[in, optional] LangID

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

반환 값

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

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

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

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

설명

드라이버는 다음 단계를 사용하여 WdfUsbTargetDeviceQueryString을 두 번 호출해야 합니다.

WdfUsbTargetDeviceQueryString이 NumCharacters 매개 변수가 가리키는 주소에 필요한 버퍼 크기를 반환하도록 String 포인터를 NULL로 설정합니다.
요청된 문자열에 있는 유니코드 문자 수를 저장할 버퍼 공간을 할당합니다. 예를 들어 드라이버는 ExAllocatePoolWithTag 를 호출하여 버퍼를 할당하거나 WdfMemoryCreate 를 호출하여 프레임워크 메모리 개체를 만들 수 있습니다.
WdfUsbTargetDeviceQueryString을 다시 호출하고 문자열 값을 새 버퍼에 대한 포인터로 설정하고 NumCharacters를 버퍼 길이(즉, 바이트 길이가 아닌 유니코드 문자 수)로 설정합니다.

WdfUsbTargetDeviceQueryString 은 지정된 USB 문자열 설명자를 찾아 설명자에서 제공된 버퍼로 유니코드 문자열을 복사합니다.

드라이버가 Request 매개 변수에 대해 NULL이 아닌 값을 지정하는 경우 프레임워크는 지정된 요청 개체를 사용하고 다른 드라이버 스레드는 필요한 경우 WdfRequestCancelSentRequest를 호출하여 문자열 쿼리 요청을 취소할 수 있습니다. 드라이버가 Request에 NULL 값을 지정하는 경우 프레임워크는 드라이버가 취소할 수 없는 내부 요청 개체를 사용합니다.

드라이버가 NULL이 아닌 요청 매개 변수를 제공하는지 NULL이 아닌 요청 매개 변수를 제공하는지 여부에 관계없이 드라이버는 NULL이 아닌 RequestOptions 매개 변수를 지정할 수 있습니다. 예를 들어 RequestOptions 매개 변수를 사용하여 제한 시간 값을 지정할 수 있습니다.

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

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

예제

다음 코드 예제에서는 WdfUsbTargetDeviceQueryString을 호출하여 필요한 버퍼 크기를 가져오고, WdfMemoryCreate 를 호출하여 메모리 개체 및 버퍼를 만든 다음, WdfUsbTargetDeviceQueryString을 다시 호출하여 USB 디바이스 설명자에서 미국 영어(0x0409)로 제조업체의 이름 문자열을 가져옵니다. (드라이버는 이전에 설명자를 드라이버 정의 컨텍스트 공간에 저장했습니다.)

PMY_DEVICE_CONTEXT  myDeviceContext;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &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)