WdfUsbTargetDeviceFormatRequestForString 함수(wdfusb.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfUsbTargetDeviceFormatRequestForString 메서드는 USB 디바이스의 문자열 인덱스 값과 연결된 USB 문자열 설명자에 대한 요청을 빌드합니다.

구문

NTSTATUS WdfUsbTargetDeviceFormatRequestForString(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         Memory,
  [in, optional] PWDFMEMORY_OFFSET Offset,
  [in]           UCHAR             StringIndex,
  [in, optional] USHORT            LangID
);

매개 변수

[in] UsbDevice

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

[in] Request

프레임워크 요청 개체에 대한 핸들입니다.

[in] Memory

프레임워크 메모리 개체에 대한 핸들입니다.

[in, optional] Offset

선택적 바이트 오프셋 및 길이 값을 제공하는 호출자가 할당한 WDFMEMORY_OFFSET 구조체에 대한 포인터입니다. 프레임워크는 이러한 값을 사용하여 문자열 설명자를 저장하기 위해 출력 버퍼 내에서 시작 주소와 길이를 결정합니다. 이 포인터가 NULL이면 설명자가 출력 버퍼의 시작 부분에 저장되고 최대 문자열 길이는 버퍼 길이입니다.

[in] StringIndex

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

[in, optional] LangID

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

반환 값

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

반환 코드	설명
STATUS_INVALID_PARAMETER	버퍼의 바이트 수가 짝수가 아니었습니다.
STATUS_INSUFFICIENT_RESOURCES	메모리가 부족했습니다.
STATUS_INTEGER_OVERFLOW	Offset이 지정하는 오프 셋 이 잘못되었습니다.

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

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

설명

WdfUsbTargetDeviceFormatRequestForString이 반환된 후 드라이버는 WdfRequestSend를 호출하여 요청을 보내야 합니다. WdfRequestSend가 반환된 후 드라이버는 메모리 핸들을 WdfMemoryGetBuffer에 전달하여 메모리 버퍼에 대한 포인터를 가져올 수 있습니다. 버퍼에는 문자열 설명자를 설명하는 USB_STRING_DESCRIPTOR 구조체가 포함됩니다.

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

예제

다음 코드 예제에서는 요청 개체와 메모리 개체를 만들고 개체 핸들을 WdfUsbTargetDeviceFormatRequestForString에 전달합니다. 그런 다음, 이 예제에서는 요청에 대한 CompletionRoutine 콜백 함수를 설정하고 요청을 I/O 대상으로 보냅니다.

NTSTATUS status;
PDEVICE_CONTEXT deviceContext = GetDeviceContext(device);
WDFREQUEST request;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
    &attributes,
    WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
    &request);

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfMemoryCreate(
    WDF_NO_OBJECT_ATTRIBUTES,
    NonPagedPool,
    0,
    STR_DESC_STRING_SIZE,
    &memHandle,
    NULL);
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(request);
    return status;
}

status = WdfUsbTargetDeviceFormatRequestForString(
    deviceContext->UsbTargetDevice,
    request,
    memHandle,
    NULL,
    deviceContext->UsbDeviceDescr.iManufacturer,
    0x0409);

if (NT_SUCCESS(status)) {
    WdfRequestSetCompletionRoutine(
        request,
        MyCompletionRoutine,
        NULL);

    if (WdfRequestSend(
            request,
            WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
            NULL)) {
        status = STATUS_PENDING;
    }
    
}
else {
    WdfObjectDelete(memHandle);
    WdfObjectDelete(request);
    return status;
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfusb.h(Wdfusb.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)