WdfUsbTargetPipeFormatRequestForWrite, fonction (wdfusb.h)

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetPipeFormatRequestForWrite génère une demande d’écriture pour un canal de sortie USB, mais elle n’envoie pas la requête.

Syntaxe

NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         WriteMemory,
  [in, optional] PWDFMEMORY_OFFSET WriteOffset
);

Paramètres

[in] Pipe

Handle vers un objet de canal d’infrastructure obtenu en appelant WdfUsbInterfaceGetConfiguredPipe.

[in] Request

Handle vers un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] WriteMemory

Handle vers un objet de mémoire d’infrastructure. Cet objet représente une mémoire tampon qui contient des données qui seront envoyées au canal. Pour plus d’informations sur cette mémoire tampon, consultez la section Remarques suivantes.

[in, optional] WriteOffset

Pointeur vers une structure d’WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse et la longueur de début, dans la mémoire tampon d’écriture, pour le transfert de données. Si ce pointeur est NULL, le transfert de données commence au début de la mémoire tampon, et la taille du transfert est la taille de la mémoire tampon.

Valeur de retour

WdfUsbTargetPipeFormatRequestForWrite retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut renvoyer l’une des valeurs suivantes :

Code de retour Description
STATUS_INVALID_PARAMETER
Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES
La mémoire insuffisante était disponible.
STATUS_INVALID_DEVICE_REQUEST
Un descripteur de mémoire non valide a été spécifié, le type du canal n’était pas valide, la direction de transfert n’était pas valide ou la requête d’E/S spécifiée était déjà mise en file d’attente vers une cible d’E/S.
STATUS_INTEGER_OVERFLOW
Décalage spécifié par le paramètre Offset spécifié.
STATUS_REQUEST_NOT_ACCEPTED
Le paquet de requête d’E/S (IRP) que le paramètre Request représente ne fournit pas suffisamment de structures IO_STACK_LOCATION pour permettre au pilote de transférer la requête.
 

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

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

Remarques

Utilisez WdfUsbTargetPipeFormatRequestForWrite, suivi de WdfRequestSend, pour envoyer des demandes d’écriture de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetPipeWriteSynchronously pour envoyer des demandes d’écriture de façon synchrone.

Le canal spécifié doit être un canal de sortie et le type du canal doit être WdfUsbPipeTypeBulk ou WdfUsbPipeTypeInterrupt.

Vous pouvez transférer une demande d’E/S que votre pilote a reçue dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande. Dans les deux cas, l’infrastructure nécessite un objet de requête et un espace de mémoire tampon.

Pour transférer une demande d’E/S que votre pilote a reçu dans une file d’attente d’E/S :

  1. Spécifiez le handle de la demande reçue pour le paramètre Request de la méthode WdfUsbTargetPipeFormatRequestForWrite.
  2. Utilisez la mémoire tampon d’entrée de la demande reçue pour le paramètre WriteMemory de la méthode WdfUsbTargetPipeFormatRequestForWrite.

    Le pilote doit appeler WdfRequestRetrieveInputMemory pour obtenir un handle vers un objet mémoire framework qui représente la mémoire tampon d’entrée de la requête et l’utiliser comme valeur pour WriteMemory.

Pour plus d’informations sur le transfert d’une requête d’E/S, consultez Demandes d’E/S de transfert.

Les pilotes divisent souvent les demandes d’E/S reçues en demandes plus petites qu’elles envoient à une cible d’E/S, de sorte que votre pilote peut créer de nouvelles demandes.

Pour créer une demande d’E/S :

  1. Créez un objet de requête et fournissez son handle pour le paramètre Request de la méthode WdfUsbTargetPipeFormatRequestForWrite.

    Appelez WdfRequestCreate pour prélocaliser un ou plusieurs objets de requête. Vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. La fonction de rappel EvtDriverDeviceAdd de votre pilote peut préallouer des objets de demande pour un appareil.

  2. Fournissez de l’espace tampon et fournissez le handle de la mémoire tampon pour le paramètre WriteMemory de la méthode WdfUsbTargetPipeFormatRequestForWrite.

    Votre pilote doit spécifier cet espace tampon en tant que handle WDFMEMORY pour la mémoire gérée par l’infrastructure. Votre pilote peut effectuer l’une des opérations suivantes :

    • Appelez WdfMemoryCreate ou WdfMemoryCreatePreallocated pour créer une mémoire tampon de mémoire, si vous souhaitez que le pilote passe une nouvelle mémoire tampon à la cible d’E/S.
    • Appelez WdfRequestRetrieveInputMemory pour obtenir un handle à l’objet mémoire qui représente la mémoire tampon d’une demande d’E/S reçue, si vous souhaitez que le pilote passe le contenu de cette mémoire tampon à la cible d’E/S.
    Notez que si votre pilote appelle WdfRequestRetrieveInputMemory et transmet le handle de mémoire à WdfUsbTargetPipeFormatRequestForWrite, le pilote ne doit pas terminer la demande d’E/S reçue tant qu’après la suppression, la réutilisation ou la reformulation de l’objet de requête créé par le pilote. (WdfUsbTargetPipeFormatRequestForWrite incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou la reformatage d’un objet de requête décrémente le nombre de références de l’objet mémoire.)
Après avoir appelé WdfUsbTargetPipeFormatRequestForWrite pour mettre en forme une requête d’E/S, le pilote doit appeler WdfRequestSend pour envoyer la requête (de façon synchrone ou asynchrone) à une cible d’E/S.

Plusieurs appels à WdfUsbTargetPipeFormatRequestForWrite qui utilisent la même requête ne provoquent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire la probabilité que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd du pilote peut appeler WdfRequestCreate pour prélocaliser un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformat (appeler WdfUsbTargetPipeFormatRequestForWrite) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une valeur de retour STATUS_INSUFFICIENT_RESOURCES d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetPipeFormatRequestForWrite pour l’objet de requête réutilisé retournent STATUS_SUCCESS, si les valeurs de paramètre ne changent pas. (Si le pilote n’appelle pas la même méthode de mise en forme de requête chaque fois, des ressources supplémentaires peuvent être allouées.)

Pour plus d’informations sur l’obtention d’informations d’état après la fin d’une demande d’E/S, consultez Obtention des informations d’achèvement.

Pour plus d’informations sur la méthode WdfUsbTargetPipeFormatRequestForWrite et les cibles d’E/S USB, consultez les cibles d’E/S USB.

Exemples

L’exemple de code suivant provient de l’exemple de pilote kmdf_fx2 . Cet exemple est une fonction de rappel EvtIoWrite qui transfère une demande d’écriture à un canal USB. L’exemple appelle WdfRequestRetrieveInputMemory pour obtenir la mémoire tampon d’entrée de la requête, puis met en forme la demande d’écriture afin que la requête puisse être envoyée à un canal USB. Ensuite, l’exemple inscrit une fonction de rappel CompletionRoutine . Enfin, il envoie la requête au canal USB.

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;
 
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkWritePipe;

    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }

    status = WdfUsbTargetPipeFormatRequestForWrite(
                                                   pipe,
                                                   Request,
                                                   reqMemory,
                                                   NULL
                                                   );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   pipe
                                   );

    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 wdfusb.h (inclure Wdfusb.h)
Bibliothèque Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Voir aussi

WdfUsbTargetPipeFormatRequestForRead