WdfUsbTargetDeviceFormatRequestForUrb 함수(wdfusb.h)

아티클
08/08/2023

[KMDF에만 적용]

WdfUsbTargetDeviceFormatRequestForUrb 메서드는 URB에서 설명하는 요청 매개 변수를 사용하여 지정된 USB 디바이스에 대한 USB 요청을 빌드하지만 요청을 보내지 않습니다.

구문

NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

매개 변수

[in] UsbDevice

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

[in] Request

프레임워크 요청 개체에 대한 핸들입니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in] UrbMemory

URB 구조체 또는 구조체의 공용 구조체 멤버 중 하나가 포함된 프레임워크 메모리 개체에 대한 핸들입니다. URB 구조체의 모든 공용 구조체 멤버에는 _URB_HEADER 구조체가 포함됩니다.

드라이버가 이전에 WdfUsbTargetDeviceCreateWithParameters 를 호출하여 UsbDevice를 만드는 경우 드라이버는 WdfUsbTargetDeviceCreateUrb 또는 WdfUsbTargetDeviceCreateIsochUrb 를 사용하여 이 메모리 개체에 포함된 URB를 만들어야 합니다. 그렇지 않으면 버그 검사 발생합니다.

[in, optional] UrbMemoryOffset

선택적 바이트 오프셋 및 길이 값을 제공하는 호출자가 할당한 WDFMEMORY_OFFSET 구조체에 대한 포인터입니다. 프레임워크는 이러한 값을 사용하여 UrbMemory 가 지정하는 메모리 내에서 URB의 시작 주소를 결정합니다. 이 포인터가 NULL이면 URB는 UrbMemory 메모리의 시작 부분에 있습니다.

반환 값

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

반환 코드	설명
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 감지되었습니다.
STATUS_INSUFFICIENT_RESOURCES	메모리가 부족했습니다.
STATUS_INTEGER_OVERFLOW	UsbMemoryOffset 매개 변수가 지정한 오프셋이 잘못되었습니다.

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

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

설명

WdfUsbTargetDeviceFormatRequestForUrb와 WdfRequestSend를 사용하여 USB 제어 전송 요청을 동기 또는 비동기적으로 보냅니다. 또는 WdfUsbTargetDeviceSendUrbSynchronously 메서드를 사용하여 요청을 동기적으로 보냅니다.

드라이버가 I/O 큐에서 받은 I/O 요청을 전달하거나 새 요청을 만들고 보낼 수 있습니다.

드라이버가 I/O 큐에서 받은 I/O 요청을 전달하려면 WdfUsbTargetDeviceFormatRequestForUrb 메서드의 Request 매개 변수에 대해 수신된 요청 의 핸들을 지정합니다.

새 I/O 요청을 만들려면 WdfRequestCreate 를 호출하여 요청 개체를 미리 할당합니다. WdfUsbTargetDeviceFormatRequestForUrb 메서드의 Request 매개 변수에 대한 요청 핸들을 입력합니다. WdfRequestReuse를 호출하여 요청 개체를 다시 사용할 수 있습니다. 드라이버의 EvtDriverDeviceAdd 콜백 함수는 디바이스에 대한 요청 개체를 미리 할당할 수 있습니다.

WdfUsbTargetDeviceFormatRequestForUrb를 호출하여 I/O 요청의 형식을 지정한 후 드라이버는 WdfRequestSend를 호출하여 요청을 I/O 대상에(동기적으로 또는 비동기적으로) 보내야 합니다. 보내기 및 잊어버리기 옵션을 사용하여 요청을 보내지 마세요.

동일한 요청을 사용하는 WdfUsbTargetDeviceFormatRequestForUrb 에 대한 여러 호출은 추가 리소스 할당을 유발하지 않습니다. 따라서 WdfRequestCreate 가 STATUS_INSUFFICIENT_RESOURCES 반환할 가능성을 줄이기 위해 드라이버의 EvtDriverDeviceAdd 콜백 함수는 WdfRequestCreate 를 호출하여 디바이스에 대해 하나 이상의 요청 개체를 미리 할당할 수 있습니다. 이후에 드라이버는 WdfRequestCreate에 대한 이후 호출에서 STATUS_INSUFFICIENT_RESOURCES 반환 값을 위험하지 않고 각 요청 개체를 다시 사용(WdfRequestReuse 호출), reformat(WdfUsbTargetDeviceFormatRequestForUrb 호출) 및 다시 보내기(WdfRequestSend 호출)할 수 있습니다. 다시 사용하는 요청 개체에 대한 WdfUsbTargetDeviceFormatRequestForUrb 에 대한 모든 후속 호출은 매개 변수 값이 변경되지 않으면 STATUS_SUCCESS 반환합니다. 드라이버가 매번 동일한 요청 형식 메서드를 호출하지 않으면 추가 리소스가 할당될 수 있습니다.

I/O 요청이 완료된 후 상태 정보를 가져오는 방법에 대한 자세한 내용은 완료 정보 가져오기를 참조하세요.

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

예제

다음 코드 예제에서는 URB 구조를 보유할 메모리 개체를 만들고, URB 구조를 초기화하고, WdfUsbTargetDeviceFormatRequestForUrb 를 호출하여 URB 구조체의 내용을 사용하는 요청의 형식을 지정합니다. 그런 다음, 이 예제에서는 CompletionRoutine 콜백 함수를 등록하고 I/O 대상에 요청을 보냅니다.

WDFMEMORY urbMemory;
URB *urbBuffer;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
                         &urbMemory,
                         NULL
                         );

if (!NT_SUCCESS(status)){
    return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
                                      urbMemory,
                                      NULL
                                      );
urbBuffer->UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceFormatRequestForUrb(
                                               deviceContext->WdfUsbTargetDevice,
                                               request,
                                               urbMemory,
                                               NULL
                                               );
WdfRequestSetCompletionRoutine(
                              request,
                              MyCompletionRoutine,
                              NULL);

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

요구 사항

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