WdfRequestSend, fonction (wdfrequest.h)

[S’applique à KMDF et à UMDF]

La méthode WdfRequestSend envoie une requête d’E/S spécifiée à une cible d’E/S spécifiée.

Syntaxe

BOOLEAN WdfRequestSend(
  [in] WDFREQUEST                Request,
  [in] WDFIOTARGET               Target,
       PWDF_REQUEST_SEND_OPTIONS Options
);

Paramètres

[in] Request

Handle vers un objet de requête d’infrastructure.

[in] Target

Handle vers un objet cible d’E/S d’infrastructure. Pour plus d’informations sur l’obtention de ce handle, consultez la section Remarques suivante.

Options

Pointeur vers une structure WDF_REQUEST_SEND_OPTIONS qui contient les options de requête fournies par l’appelant. Ce paramètre est facultatif et peut être NULL si vous ne souhaitez pas activer d’options de requête.

Valeur de retour

WdfRequestSend retourne TRUE si la requête a été envoyée à la cible. Sinon, cette méthode retourne FALSE.

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

L’objet de requête spécifié par le pilote pour le paramètre Request peut être celui qu’il a reçu ou celui qu’il a créé en appelant la méthode WdfRequestCreate .

Pour obtenir un handle vers un objet cible d’E/S, le pilote peut effectuer l’une des opérations suivantes :

Par défaut, WdfRequestSend remet la requête à la cible de manière asynchrone, ce qui signifie qu’elle retourne immédiatement sans attendre que la demande soit terminée. Si vous le souhaitez, la requête peut être remise de manière synchrone, ce qui signifie que WdfRequestSend ne retourne pas tant qu’un pilote n’a pas terminé la requête. Pour envoyer la requête de manière synchrone, le pilote doit définir l’indicateur WDF_REQUEST_SEND_OPTION_SYNCHRONOUS dans la structure WDF_REQUEST_SEND_OPTIONS .

Si WdfRequestSend échoue ou si votre pilote définit l’indicateur WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, le pilote peut appeler WdfRequestGetStatus immédiatement après l’appel de WdfRequestSend.

Si WdfRequestSend réussit et que votre pilote ne définit pas l’indicateur WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, le pilote appelle généralement WdfRequestGetStatus à partir d’une fonction de rappel CompletionRoutine .

Si le pilote envoie la requête de manière synchrone, nous vous recommandons de définir une valeur de délai d’attente dans la structure WDF_REQUEST_SEND_OPTIONS et l’indicateur de délai d’attente dans le membre Indicateurs de cette structure.

Si le pilote fournit une valeur de délai d’attente, il doit appeler WdfRequestAllocateTimer avant d’appeler WdfRequestSend. Cela garantit que WdfRequestSend n’échouera pas s’il n’y a pas de ressources système insuffisantes pour allouer un minuteur.

Si le pilote définit l’indicateur WDF_REQUEST_SEND_OPTION_SYNCHRONOUS , il doit appeler WdfRequestSend à IRQL = PASSIVE_LEVEL. Si cet indicateur n’est pas défini, le pilote doit appeler cette méthode à IRQL <= DISPATCH_LEVEL. WdfRequestSend envoie la requête au runtime IRQL de l’appelant.

Un pilote ne peut pas appeler WdfRequestSend pour envoyer une requête d’E/S à un canal USB, si le pilote a configuré un lecteur continu pour le canal.

Lors de l’envoi d’une requête à un pilote UMDF, un pilote en mode noyau doit respecter les restrictions IRQL décrites dans Prise en charge des clients Kernel-Mode dans les pilotes UMDF.

Pour plus d’informations sur WdfRequestSend, consultez Demandes d’E/S de transfert.

Exemples

L’exemple de code suivant est une version abrégée d’une fonction de rappel EvtIoWrite à partir de l’exemple de pilote kmdf_fx2 . La fonction valide la longueur de la mémoire tampon de la requête, obtient un handle à la mémoire tampon, met en forme la requête pour une cible USB et envoie la requête.

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    UNREFERENCED_PARAMETER(Queue);
    //
    // Check if the transfer size is valid.
    //
    if (Length > MAX_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }
    //
    // Get driver-defined context space from
    // the device object. The driver stored the
    // pipe handle there.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;
 
    //
    // Get a handle to a memory object that represents
    // the input buffer.
    //
    status = WdfRequestRetrieveInputMemory(Request, &reqMemory);
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request so it can be sent to a USB target.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                            pipe,
                            Request,
                            reqMemory,
                            NULL // Offsets
                            ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    //
    // Set a CompletionRoutine callback function.
    //
    WdfRequestSetCompletionRoutine(
                            Request,
                            EvtRequestReadCompletionRoutine,
                            pipe
                            );
    //
    // Send the request. If an error occurs, complete the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Configuration requise

   
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2,0
En-tête wdfrequest.h (include Wdf.h)
Bibliothèque Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL Voir la section Notes.
Règles de conformité DDI DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), ReqCompletionRoutine(kmdf), ReqMarkCancelableSend(kmdf), ReqSendFail(kmdf), ReqSendWhileSpinlock(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), RequestFormattedValid(kmdf), RequestGetStatusValid(kmdf), RequestGetStatusValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), SyncReqSend2(kmdf), WdfRequestSendSyncAtDispatch(kmdf), WdfRequestSendSyncAtDispatch2(kmdf)

Voir aussi

CompletionRoutine

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfRequestAllocateTimer

WdfRequestCreate

WdfRequestGetStatus