Fonction WdfRequestSend (wdfrequest.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfRequestSend envoie une demande 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 d’un objet de requête d’infrastructure.

[in] Target

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

Options

Pointeur vers une structure de WDF_REQUEST_SEND_OPTIONS qui contient des options de requête fournies par l’appelant. Ce paramètre est facultatif et peut avoir la valeur NULL si vous ne souhaitez activer aucune option de requête.

Valeur retournée

WdfRequestSend retourne TRUE si la demande a été envoyée à la cible. Sinon, cette méthode retourne FALSE, et l’appel de WdfRequestGetStatus renvoie un status qui échoue à un test NT_SUCCESS().

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

Remarques

L’objet de requête que le pilote spécifie 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 pour un objet cible d’E/S, le pilote peut effectuer l’une des opérations suivantes :

Si le pilote utilise des cibles d’E/S générales, il appelle WdfDeviceGetIoTarget. Pour plus d’informations, consultez Initialisation d’une cible d’E/S générale.
Si le pilote utilise une cible d’E/S spécialisée, il appelle une ou plusieurs méthodes que l’objet cible spécialisé définit. Par exemple, un pilote pour un périphérique USB peut appeler WdfUsbTargetDeviceGetIoTarget ou WdfUsbTargetPipeGetIoTarget.

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 demande peut être remise de manière synchrone, ce qui signifie que WdfRequestSend ne retourne pas tant qu’un pilote n’a pas terminé la demande. 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 avoir appelé 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 Flags 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 suffisantes pour allouer un minuteur.

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

Un pilote ne peut pas appeler WdfRequestSend pour envoyer une demande 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 Transfert des demandes d’E/S.

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 dans 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

Condition requise	Valeur
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	Consultez 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), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), SyncReqSend2(kmdf), WdfRequestSendSyncAtDispatch(kmdf), WdfRequestSendSyncAtDispatch2(kmdf)