WdfRequestCompleteWithInformation 함수(wdfrequest.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfRequestCompleteWithInformation 메서드는 완료 정보를 저장한 다음 제공된 완료 상태 사용하여 지정된 I/O 요청을 완료합니다.

구문

void WdfRequestCompleteWithInformation(
  [in] WDFREQUEST Request,
  [in] NTSTATUS   Status,
  [in] ULONG_PTR  Information
);

매개 변수

[in] Request

요청 개체에 대한 핸들입니다.

[in] Status

요청의 완료 상태 나타내는 NTSTATUS 값입니다. 유효한 상태 값에는 다음이 포함되지만 이에 국한되지는 않습니다.

STATUS_SUCCESS

드라이버가 요청을 성공적으로 완료했습니다.

STATUS_CANCELLED

드라이버가 요청을 취소했습니다.

STATUS_UNSUCCESSFUL

드라이버에서 요청을 처리하는 동안 오류가 발생했습니다.

[in] Information

요청 종속 값으로 설정된 ULONG_PTR. 예를 들어 전송 요청이 성공적으로 완료되면 전송된 바이트 수로 설정됩니다. 이 필드는 드라이버에서 확장할 수 없습니다.

반환 값

없음

설명

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

읽기, 쓰기 및 IOCTL 요청의 경우 드라이버가 WdfRequestCompleteWithInformation을 호출해야 합니다.

비데이터 전송 요청의 경우 대신 WdfRequestComplete 를 호출하는 것이 옵션입니다.

WdfRequestCompleteWithInformation을 호출하는 것은 WdfRequestSetInformation을 호출한 다음 WdfRequestComplete를 호출하는 것과 같습니다.

WdfRequestCompleteWithInformation이 반환되면 드라이버가 요청 개체에 하나 이상의 추가 참조 수를 추가하기 위해 WdfObjectReference를 호출하지 않는 한 요청 핸들은 더 이상 유효하지 않습니다. WdfRequestCompleteWithInformation이 반환된 후 드라이버는 WdfObjectReference를 호출한 경우에도 연결된 WDM IRP 구조체에 액세스하려고 시도해서는 안됩니다.

드라이버가 WdfRequestCompleteWithInformation을 호출할 때 프레임워크는 시스템에서 I/O 작업을 요청한 스레드의 런타임 우선 순위를 높이는 데 사용하는 기본값을 제공합니다. 기본 우선 순위 상승 값에 대한 자세한 내용은 I/O 요청을 완료할 때 우선 순위 상승 지정을 참조하세요. 드라이버는 WdfRequestCompleteWithPriorityBoost 를 호출하여 기본 우선 순위 상승 값을 재정의할 수 있습니다.

WdfRequestCompleteWithInformation 호출에 대한 자세한 내용은 I/O 요청 완료를 참조하세요.

WdfRequestCompleteWithInformation을 사용하여 복사된 바이트 수를 검색하는 방법을 보여 주는 코드 예제는 VirtualSerial2 드라이버 샘플을 참조하세요.

예제

다음 코드 예제에서는 USB 디바이스용 드라이버가 CompletionRoutine 콜백 함수 에서 WdfRequestCompleteWithInformation을 호출하는 방법을 보여줍니다.

VOID
EvtRequestReadCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{    
    NTSTATUS  status;
    size_t  bytesRead = 0;
    PWDF_USB_REQUEST_COMPLETION_PARAMS  usbCompletionParams;

    UNREFERENCED_PARAMETER(Target);
    UNREFERENCED_PARAMETER(Context);

    status = CompletionParams->IoStatus.Status;
    usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
    bytesRead =  usbCompletionParams->Parameters.PipeRead.Length;
 
    if (NT_SUCCESS(status)){
        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    DBG_READ,
                    "Number of bytes read: %I64d\n",
                    (INT64)bytesRead
                    );
    } else {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_READ,
                    "Read failed - request status 0x%x UsbdStatus 0x%x\n",
                    status,
                    usbCompletionParams->UsbdStatus
                    );
    }
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesRead
                                      );
    return;
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfrequest.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 규정 준수 규칙	BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWrite(kmdf), BufAfterReqCompletedWriteA(kmdf), CompleteCanceledReq(kmdf), DeferredRequestCompleted(kmdf), DoubleCompletion(kmdf), DoubleCompletionLocal(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtSurpriseRemoveNoRequestComplete(kmdf), InvalidReqAccess(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MarkCancOnCancReqLocal(kmdf), MdlAfterReqCompletedIntIoctl(kmdf), MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctl(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedRead(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWrite(kmdf), MdlAfterReqCompletedWriteA(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), MemAfterReqCompletedWriteA(kmdf), NoCancelFromEvtSurpriseRemove(kmdf), ReqDelete(kmdf), ReqIsCancOnCancReq(kmdf), ReqNotCanceledLocal(kmdf), ReqSendFail(kmdf), RequestCompletedLocal(kmdf), RequestCompletedLocal(kmdf)