WdfRequestSend 함수(wdfrequest.h)

아티클
06/20/2023

[KMDF 및 UMDF에 적용]

WdfRequestSend 메서드는 지정된 I/O 요청을 지정된 I/O 대상으로 보냅니다.

구문

BOOLEAN WdfRequestSend(
  [in] WDFREQUEST                Request,
  [in] WDFIOTARGET               Target,
       PWDF_REQUEST_SEND_OPTIONS Options
);

매개 변수

[in] Request

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

[in] Target

프레임워크 I/O 대상 개체에 대한 핸들입니다. 이 핸들을 가져오는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.

Options

호출자가 제공한 요청 옵션을 포함하는 WDF_REQUEST_SEND_OPTIONS 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 요청 옵션을 사용하지 않으려는 경우 NULL 일 수 있습니다.

반환 값

요청이 대상으로 전송된 경우 WdfRequestSend는 TRUE를 반환합니다. 그렇지 않으면 이 메서드는 FALSE를 반환하고 WdfRequestGetStatus를 호출하면 NT_SUCCESS() 테스트에 실패하는 상태 반환됩니다.

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

설명

드라이버가 Request 매개 변수에 대해 지정하는 요청 개체는 받은 개체이거나 WdfRequestCreate 메서드를 호출하여 만든 개체일 수 있습니다.

I/O 대상 개체에 대한 핸들을 가져오기 위해 드라이버는 다음 중 하나를 수행할 수 있습니다.

드라이버가 일반 I/O 대상을 사용하는 경우 WdfDeviceGetIoTarget을 호출합니다. 자세한 내용은 일반 I/O 대상 초기화를 참조하세요.
드라이버가 특수 I/O 대상을 사용하는 경우 특수 대상 개체가 정의하는 하나 이상의 메서드를 호출합니다. 예를 들어 USB 디바이스용 드라이버는 WdfUsbTargetDeviceGetIoTarget 또는 WdfUsbTargetPipeGetIoTarget을 호출할 수 있습니다.

기본적으로 WdfRequestSend 는 요청을 대상에 비동기적으로 전달합니다. 즉, 요청이 완료될 때까지 기다리지 않고 즉시 반환됩니다. 필요에 따라 요청은 동기적으로 배달될 수 있습니다. 즉, 드라이버가 요청을 완료할 때까지 WdfRequestSend 가 반환되지 않습니다. 요청을 동기적으로 보내려면 드라이버가 WDF_REQUEST_SEND_OPTIONS 구조에서WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 플래그를 설정해야 합니다.

WdfRequestSend가 실패하거나 드라이버가 WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 플래그를 설정하는 경우 드라이버는 WdfRequestSend를 호출한 직후 WdfRequestGetStatus를 호출할 수 있습니다.

WdfRequestSend가 성공하고 드라이버가 WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 플래그를 설정하지 않으면 드라이버는 일반적으로 CompletionRoutine 콜백 함수 내에서 WdfRequestGetStatus를 호출합니다.

드라이버가 요청을 동기적으로 보내는 경우 드라이버는 이 구조체의 Flags 멤버에서 WDF_REQUEST_SEND_OPTIONS 구조체 및 제한 시간 플래그에 시간 제한 값을 설정하는 것이 좋습니다.

드라이버가 시간 제한 값을 제공하는 경우 WdfRequestSend를 호출하기 전에 WdfRequestAllocateTimer를 호출해야 합니다. 이렇게 하면 타이머를 할당할 시스템 리소스가 부족한 경우 WdfRequestSend 가 실패하지 않습니다.

드라이버가 WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 플래그를 설정하는 경우 IRQL = PASSIVE_LEVELWdfRequestSend 를 호출해야 합니다. 이 플래그가 설정되지 않은 경우 드라이버는 IRQL <= DISPATCH_LEVEL 이 메서드를 호출해야 합니다. WdfRequestSend 는 호출자의 IRQL에서 요청을 보냅니다.

드라이버가 파이프에 대한 연속 판독기를 구성한 경우 드라이버는 WdfRequestSend를 호출하여 USB 파이프에 I/O 요청을 보낼 수 없습니다.

UMDF 드라이버에 요청을 보낼 때 커널 모드 드라이버는 UMDF 드라이버에서 Kernel-Mode 클라이언트 지원에 설명된 IRQL 제한을 따라야 합니다.

WdfRequestSend에 대한 자세한 내용은 I/O 요청 전달을 참조하세요.

예제

다음 코드 예제는 kmdf_fx2 샘플 드라이버에서 EvtIoWrite 콜백 함수의 단축된 버전입니다. 함수는 요청의 버퍼 길이를 확인하고, 버퍼에 대한 핸들을 가져오고, USB 대상에 대한 요청의 형식을 지정하고, 요청을 보냅니다.

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    UNREFERENCED_PARAMETER(Queue);
    //
    // Check if the transfer size is valid.
    //
    if (Length > MAX_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }
    //
    // Get driver-defined context space from
    // the device object. The driver stored the
    // pipe handle there.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;
 
    //
    // Get a handle to a memory object that represents
    // the input buffer.
    //
    status = WdfRequestRetrieveInputMemory(Request, &reqMemory);
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request so it can be sent to a USB target.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                            pipe,
                            Request,
                            reqMemory,
                            NULL // Offsets
                            ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    //
    // Set a CompletionRoutine callback function.
    //
    WdfRequestSetCompletionRoutine(
                            Request,
                            EvtRequestReadCompletionRoutine,
                            pipe
                            );
    //
    // Send the request. If an error occurs, complete the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfrequest.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	설명 섹션을 참조하십시오.
DDI 규정 준수 규칙	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), ReqCompletionRoutine(kmdf), ReqMarkCancelableSend(kmdf), ReqSendFail(kmdf), ReqSendWhileSpinlock(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), RequestFormattedValid(kmdf), RequestGetStatusValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), SyncReqSend2(kmdf), WdfRequestSendSyncAtDispatch(kmdf), WdfRequestSendSyncAtDispatch2(kmdf)