Função WdfRequestCompleteWithInformation (wdfrequest.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfRequestCompleteWithInformation armazena informações de conclusão e, em seguida, conclui uma solicitação de E/S especificada com uma status de conclusão fornecida.

Sintaxe

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

Parâmetros

[in] Request

Um identificador para o objeto de solicitação.

[in] Status

Um valor NTSTATUS que representa o status de conclusão da solicitação. Os valores de status válidos incluem, mas não se limitam a:

STATUS_SUCCESS

O driver concluiu a solicitação com êxito.

STATUS_CANCELLED

O driver cancelou a solicitação.

STATUS_UNSUCCESSFUL

O driver encontrou um erro ao processar a solicitação.

[in] Information

Um ULONG_PTR definido como um valor dependente de solicitação. Por exemplo, após a conclusão bem-sucedida de uma solicitação de transferência, isso é definido como o número de bytes transferidos. Esse campo não é extensível pelo driver.

Retornar valor

Nenhum

Comentários

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Para solicitações de leitura, gravação e IOCTL, é necessário que o driver chame WdfRequestCompleteWithInformation

Para uma solicitação de transferência não de dados, chamar WdfRequestComplete é uma opção.

Chamar WdfRequestCompleteWithInformation é equivalente a chamar WdfRequestSetInformation e, em seguida, chamar WdfRequestComplete.

Depois que uma chamada para WdfRequestCompleteWithInformation é retornada, o identificador de solicitação não é mais válido, a menos que o driver tenha chamado WdfObjectReference para adicionar uma ou mais contagens de referência adicionais ao objeto de solicitação. Observe que, depois que WdfRequestCompleteWithInformation retornar, o driver não deve tentar acessar a estrutura WDM IRP associada, mesmo que tenha chamado WdfObjectReference.

Quando o driver chama WdfRequestCompleteWithInformation, a estrutura fornece um valor padrão que o sistema usa para aumentar a prioridade de tempo de execução do thread que solicitou a operação de E/S. Para obter informações sobre valores de aumento de prioridade padrão, consulte Especificando aumentos de prioridade ao concluir solicitações de E/S. Seu driver pode chamar WdfRequestCompleteWithPriorityBoost para substituir o valor de aumento de prioridade padrão.

Para obter mais informações sobre como chamar WdfRequestCompleteWithInformation, consulte Concluindo solicitações de E/S.

Para obter um exemplo de código que mostra como usar WdfRequestCompleteWithInformation para recuperar o número de bytes copiados, consulte o exemplo de driver VirtualSerial2.

Exemplos

O exemplo de código a seguir mostra como um driver para um dispositivo USB pode chamar WdfRequestCompleteWithInformation em uma função de retorno de chamada 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	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfrequest.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da 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)