WdfRequestCompleteWithInformation, fonction (wdfrequest.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfRequestCompleteWithInformation stocke les informations d’achèvement, puis termine une demande d’E/S spécifiée avec un status d’achèvement fourni.

Syntaxe

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

Paramètres

[in] Request

Handle de l’objet de requête.

[in] Status

Valeur NTSTATUS qui représente l’achèvement status de la requête. Les valeurs status valides incluent, sans s’y limiter, les éléments suivants :

STATUS_SUCCESS

Le pilote a correctement effectué la demande.

STATUS_CANCELLED

Le pilote a annulé la demande.

STATUS_UNSUCCESSFUL

Le pilote a rencontré une erreur lors du traitement de la demande.

[in] Information

Un ULONG_PTR défini sur une valeur dépendante de la demande. Par exemple, en cas de réussite d’une demande de transfert, ce paramètre est défini sur le nombre d’octets transférés. Ce champ n’est pas extensible par le pilote.

Valeur de retour

None

Remarques

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Pour les demandes de lecture, d’écriture et IOCTL, il est nécessaire que le pilote appelle WdfRequestCompleteWithInformation

Pour une demande non-transfert de données, l’appel de WdfRequestComplete à la place est une option.

Appeler WdfRequestCompleteWithInformation revient à appeler WdfRequestSetInformation , puis à appeler WdfRequestComplete.

Après un appel à WdfRequestCompleteWithInformation retourné, le handle de requête n’est plus valide, sauf si le pilote a appelé WdfObjectReference pour ajouter un ou plusieurs nombres de références supplémentaires à l’objet de requête. Notez qu’après le retour de WdfRequestCompleteWithInformation , le pilote ne doit pas tenter d’accéder à la structure IRP WDM associée, même s’il a appelé WdfObjectReference.

Lorsque votre pilote appelle WdfRequestCompleteWithInformation, l’infrastructure fournit une valeur par défaut que le système utilise pour améliorer la priorité d’exécution du thread qui a demandé l’opération d’E/S. Pour plus d’informations sur les valeurs d’augmentation de priorité par défaut, consultez Spécification des augmentations de priorité lors de l’exécution des demandes d’E/S. Votre pilote peut appeler WdfRequestCompleteWithPriorityBoost pour remplacer la valeur d’augmentation de priorité par défaut.

Pour plus d’informations sur l’appel de WdfRequestCompleteWithInformation, consultez Achèvement des demandes d’E/S.

Pour obtenir un exemple de code qui montre comment utiliser WdfRequestCompleteWithInformation pour récupérer le nombre d’octets copiés, consultez l’exemple de pilote VirtualSerial2.

Exemples

L’exemple de code suivant montre comment un pilote pour un périphérique USB peut appeler WdfRequestCompleteWithInformation dans une fonction de rappel 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;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfrequest.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de 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)