Función WdfRequestCompleteWithInformation (wdfrequest.h)

Artículo
02/27/2024

[Se aplica a KMDF y UMDF]

El método WdfRequestCompleteWithInformation almacena información de finalización y, a continuación, completa una solicitud de E/S especificada con un estado de finalización proporcionado.

Sintaxis

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

Parámetros

[in] Request

Identificador del objeto de solicitud.

[in] Status

Valor NTSTATUS que representa el estado de finalización de la solicitud. Entre los valores de estado válidos se incluyen, entre otros, los siguientes:

STATUS_SUCCESS

El controlador completó correctamente la solicitud.

STATUS_CANCELLED

El controlador canceló la solicitud.

STATUS_UNSUCCESSFUL

El controlador encontró un error al procesar la solicitud.

[in] Information

Un ULONG_PTR que se establece en un valor dependiente de la solicitud. Por ejemplo, al completar correctamente una solicitud de transferencia, se establece en el número de bytes transferidos. Este campo no es extensible por el controlador.

Valor devuelto

None

Observaciones

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Para las solicitudes de lectura, escritura e IOCTL, es necesario que el controlador llame a WdfRequestCompleteWithInformation.

Para una solicitud de transferencia de datos, llamar a WdfRequestComplete en su lugar es una opción.

Llamar a WdfRequestCompleteWithInformation equivale a llamar a WdfRequestSetInformation y, a continuación, llamar a WdfRequestComplete.

Una vez que se devuelve una llamada a WdfRequestCompleteWithInformation , el identificador de solicitud ya no es válido a menos que el controlador haya llamado A WdfObjectReference para agregar uno o varios recuentos de referencia adicionales al objeto de solicitud. Tenga en cuenta que después de que WdfRequestCompleteWithInformation devuelva, el controlador no debe intentar acceder a la estructura IRP de WDM asociada, incluso si se ha llamado a WdfObjectReference.

Cuando el controlador llama a WdfRequestCompleteWithInformation, el marco proporciona un valor predeterminado que el sistema usa para aumentar la prioridad en tiempo de ejecución del subproceso que solicitó la operación de E/S. Para obtener información sobre los valores predeterminados de optimización de prioridad, vea Especificar aumentos de prioridad al completar solicitudes de E/S. El controlador puede llamar a WdfRequestCompleteWithPriorityBoost para invalidar el valor de aumento de prioridad predeterminado.

Para obtener más información sobre cómo llamar a WdfRequestCompleteWithInformation, consulte Finalización de solicitudes de E/S.

Para obtener un ejemplo de código que muestra cómo usar WdfRequestCompleteWithInformation para recuperar el número de bytes copiados, consulte el ejemplo del controlador VirtualSerial2.

Ejemplos

En el ejemplo de código siguiente se muestra cómo un controlador para un dispositivo USB podría llamar a WdfRequestCompleteWithInformation en una función de devolución de llamada 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;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfrequest.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de 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)