WdfUsbTargetDeviceQueryString 함수(wdfusb.h)

[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 반환하면 변수는 String 버퍼가 수신하는 유니코드 문자열에 있는 문자 수(제공된 경우 NULL 종결자 포함)를 받습니다.

[in] StringIndex

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

[in, optional] LangID

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

반환 값

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

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

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

발언

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

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

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

드라이버가NULL이 아닌 또는 NULLRequest 매개 변수를 제공하는지 여부에 관계없이 드라이버에서NULLRequestOptions 매개 변수를 지정할 수 있습니다. 예를 들어 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
                                       );

요구 사항

참고 항목

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters