Funzione WdfRequestCompleteWithInformation (wdfrequest.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRequestCompleteWithInformation archivia le informazioni di completamento e quindi completa una richiesta di I/O specificata con uno stato di completamento specificato.

Sintassi

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

Parametri

[in] Request

Handle per l'oggetto request.

[in] Status

Valore NTSTATUS che rappresenta lo stato di completamento della richiesta. I valori di stato validi includono, ma non sono limitati a, quanto segue:

STATUS_SUCCESS

Il driver ha completato correttamente la richiesta.

STATUS_CANCELLED

Il driver ha annullato la richiesta.

STATUS_UNSUCCESSFUL

Il driver ha rilevato un errore durante l'elaborazione della richiesta.

[in] Information

Un ULONG_PTR impostato su un valore dipendente dalla richiesta. Ad esempio, al completamento di una richiesta di trasferimento, viene impostato sul numero di byte trasferiti. Questo campo non è estendibile dal driver.

Valore restituito

nessuno

Osservazioni

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Per le richieste di lettura, scrittura e IOCTL, è necessario che il driver chiami WdfRequestCompleteWithInformation

Per una richiesta di trasferimento non dati, chiamare WdfRequestComplete è invece un'opzione.

La chiamata a WdfRequestCompleteWithInformation equivale a chiamare WdfRequestSetInformation e quindi chiamare WdfRequestComplete.

Dopo la restituzione di una chiamata a WdfRequestCompleteWithInformation , l'handle della richiesta non è più valido a meno che il driver non abbia chiamato WdfObjectReference per aggiungere uno o più conteggi di riferimento aggiuntivi all'oggetto request. Si noti che dopo che WdfRequestCompleteWithInformation restituisce , il driver non deve tentare di accedere alla struttura WDM IRP associata, anche se ha chiamato WdfObjectReference.

Quando il driver chiama WdfRequestCompleteWithInformation, il framework fornisce un valore predefinito usato dal sistema per aumentare la priorità di runtime del thread che ha richiesto l'operazione di I/O. Per informazioni sui valori di aumento della priorità predefinita, vedere Specifica di incrementi di priorità durante il completamento delle richieste di I/O. Il driver può chiamare WdfRequestCompleteWithPriorityBoost per eseguire l'override del valore di boost di priorità predefinito.

Per altre informazioni sulla chiamata a WdfRequestCompleteWithInformation, vedere Completamento delle richieste di I/O.

Per un esempio di codice che illustra come usare WdfRequestCompleteWithInformation per recuperare il numero di byte copiati, vedere l'esempio di driver VirtualSerial2.

Esempio

Nell'esempio di codice seguente viene illustrato come un driver per un dispositivo USB potrebbe chiamare WdfRequestCompleteWithInformation in una funzione di callback di CompletamentoRoutine .

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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfrequest.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità 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)