Функция WdfRequestCompleteWithInformation (wdfrequest.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfRequestCompleteWithInformation сохраняет сведения о завершении, а затем завершает указанный запрос ввода-вывода с указанным состоянием завершения.

Синтаксис

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, для этого задано значение, зависящее от запроса. Например, при успешном выполнении запроса на передачу устанавливается количество переданных байтов. Это поле не расширяемо драйвером.

Возвращаемое значение

None

Remarks

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Для запросов чтения, записи и IOCTL драйверу необходимо вызвать WdfRequestCompleteWithInformation.

Для запроса, отличного от передачи данных, вызов WdfRequestComplete является вариантом.

Вызов WdfRequestCompleteWithInformation эквивалентен вызову WdfRequestSetInformation и последующему вызову WdfRequestComplete.

После возврата вызова WdfRequestCompleteWithInformation дескриптор запроса становится недействительным, если драйвер не вызвал WdfObjectReference для добавления одного или нескольких дополнительных счетчиков ссылок в объект запроса. Обратите внимание, что после возврата WdfRequestCompleteWithInformation драйвер не должен пытаться получить доступ к связанной структуре WDM IRP, даже если он вызвал WdfObjectReference.

Когда драйвер вызывает WdfRequestCompleteWithInformation, платформа предоставляет значение по умолчанию, которое система использует для повышения приоритета во время выполнения потока, запрашивающего операцию ввода-вывода. Сведения о значениях повышения приоритета по умолчанию см. в разделе Указание повышения приоритета при выполнении запросов ввода-вывода. Драйвер может вызвать WdfRequestCompleteWithPriorityBoost , чтобы переопределить значение повышения приоритета по умолчанию.

Дополнительные сведения о вызове WdfRequestCompleteWithInformation см. в разделе Завершение запросов ввода-вывода.

Пример кода, демонстрирующий использование WdfRequestCompleteWithInformation для получения количества скопированных байтов, см. в примере драйвера VirtualSerial2.

Примеры

В следующем примере кода показано, как драйвер для USB-устройства может вызывать WdfRequestCompleteWithInformation в функции обратного вызова CompletionRoutine .

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), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)