WdfRequestCompleteWithInformation-Funktion (wdfrequest.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfRequestCompleteWithInformation-Methode speichert Vervollständigungsinformationen und schließt dann eine angegebene E/A-Anforderung mit einer angegebenen Vervollständigung status ab.

Syntax

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

Parameter

[in] Request

Ein Handle für das Anforderungsobjekt.

[in] Status

Ein NTSTATUS-Wert, der die Vervollständigung status der Anforderung darstellt. Gültige status-Werte umfassen folgendes, sind jedoch nicht beschränkt auf:

STATUS_SUCCESS

Der Treiber hat die Anforderung erfolgreich abgeschlossen.

STATUS_CANCELLED

Der Treiber hat die Anforderung abgebrochen.

STATUS_UNSUCCESSFUL

Beim Treiber ist beim Verarbeiten der Anforderung ein Fehler aufgetreten.

[in] Information

Ein ULONG_PTR, der auf einen anforderungsabhängigen Wert festgelegt ist. Wenn beispielsweise eine Übertragungsanforderung erfolgreich abgeschlossen wurde, wird dies auf die Anzahl der übertragenen Bytes festgelegt. Dieses Feld ist vom Treiber nicht erweiterbar.

Rückgabewert

Keine

Bemerkungen

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Für Lese-, Schreib- und IOCTL-Anforderungen muss der Treiber WdfRequestCompleteWithInformation aufrufen.

Für eine Anforderung ohne Datenübertragung ist das Aufrufen von WdfRequestComplete stattdessen eine Option.

Das Aufrufen von WdfRequestCompleteWithInformation entspricht dem Aufrufen von WdfRequestSetInformation und dann dem Aufrufen von WdfRequestComplete.

Nachdem ein Aufruf von WdfRequestCompleteWithInformation zurückgegeben wurde, ist das Anforderungshandle nicht mehr gültig, es sei denn, der Treiber hat WdfObjectReference aufgerufen, um dem Anforderungsobjekt eine oder mehrere zusätzliche Verweisanzahlen hinzuzufügen. Beachten Sie, dass der Treiber nach der Rückgabe von WdfRequestCompleteWithInformation nicht versuchen darf, auf die zugeordnete WDM-IRP-Struktur zuzugreifen, auch wenn er WdfObjectReference aufgerufen hat.

Wenn Ihr Treiber WdfRequestCompleteWithInformation aufruft, stellt das Framework einen Standardwert bereit, den das System verwendet, um die Laufzeitpriorität des Threads zu erhöhen, der den E/A-Vorgang angefordert hat. Informationen zu Standardprioritätssteigerungswerten finden Sie unter Angeben von Prioritätssteigerungen beim Abschließen von E/A-Anforderungen. Ihr Treiber kann WdfRequestCompleteWithPriorityBoost aufrufen, um den Standardwert der Prioritätserhöhung außer Kraft zu setzen.

Weitere Informationen zum Aufrufen von WdfRequestCompleteWithInformation finden Sie unter Abschließen von E/A-Anforderungen.

Ein Codebeispiel, das zeigt, wie WdfRequestCompleteWithInformation zum Abrufen der Anzahl kopierter Bytes verwendet wird, finden Sie im VirtualSerial2-Treiberbeispiel.

Beispiele

Das folgende Codebeispiel zeigt, wie ein Treiber für ein USB-Gerät WdfRequestCompleteWithInformation in einer CompletionRoutine-Rückruffunktion aufrufen kann.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfrequest.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	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)