WdfUsbTargetPipeFormatRequestForRead, fonction (wdfusb.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetPipeFormatRequestForRead génère une demande de lecture pour un canal d’entrée USB, mais elle n’envoie pas la requête.

Syntaxe

NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         ReadMemory,
  [in, optional] PWDFMEMORY_OFFSET ReadOffset
);

Paramètres

[in] Pipe

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

[in] Request

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

[in, optional] ReadMemory

Handle pour un objet de mémoire d’infrastructure. Cet objet représente une mémoire tampon qui recevra les données du canal. La taille de la mémoire tampon doit être un multiple de la taille maximale des paquets du canal, sauf si le pilote a appelé WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. Pour plus d’informations sur cette mémoire tampon, consultez la section Remarques suivante.

[in, optional] ReadOffset

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

Valeur retournée

WdfUsbTargetPipeFormatRequestForRead retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner 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 disponible était insuffisante.
STATUS_INVALID_DEVICE_REQUEST	Un descripteur de mémoire non valide a été spécifié, le type du canal n’était pas valide, le sens du transfert n’était pas valide ou la demande 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 que le paramètre Offset a spécifié n’est pas valide.
STATUS_INVALID_BUFFER_SIZE	La taille de la mémoire tampon n’était pas un multiple de la taille maximale des paquets du canal. La taille de la mémoire tampon doit être un multiple de la taille maximale des paquets du canal, sauf si le pilote a appelé WdfUsbTargetPipeSetNoMaximumPacketSizeCheck.
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de demandes d’E/S (IRP) que représente le paramètre Request 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.

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

Remarques

Utilisez WdfUsbTargetPipeFormatRequestForRead, suivi de WdfRequestSend, pour envoyer des demandes de lecture de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetPipeReadSynchronously pour envoyer des demandes de lecture de manière synchrone.

Le canal spécifié par le paramètre Pipe doit être un canal d’entrée, 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 reçue par votre pilote dans une file d’attente d’E/S :

Spécifiez le handle de la requête reçue pour le paramètre Request de la méthode WdfUsbTargetPipeFormatRequestForRead.
Utilisez la mémoire tampon de sortie de la requête reçue pour le paramètre ReadMemory de la méthode WdfUsbTargetPipeFormatRequestForRead.
Le pilote doit appeler WdfRequestRetrieveOutputMemory pour obtenir un handle pour un objet de mémoire d’infrastructure qui représente la mémoire tampon de sortie de la requête, et utiliser ce handle comme valeur pour le paramètre ReadMemory .

Pour plus d’informations sur le transfert d’une demande d’E/S, consultez Transfert de demandes d’E/S.

Les pilotes divisent souvent les demandes d’E/S reçues en demandes plus petites qu’ils 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 :

Créez un objet de requête et fournissez son handle pour le paramètre Request de la méthode WdfUsbTargetPipeFormatRequestForRead.
Appelez WdfRequestCreate pour préallouer 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 requête pour un appareil.
Fournissez de l’espace tampon et fournissez le handle de la mémoire tampon pour le paramètre ReadMemory de la méthode WdfUsbTargetPipeFormatRequestForRead.
Votre pilote doit spécifier cet espace de mémoire 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, si vous souhaitez que le pilote passe une nouvelle mémoire tampon à la cible d’E/S.
- Appelez WdfRequestRetrieveOutputMemory pour obtenir un handle à l’objet mémoire qui représente la mémoire tampon d’une requête 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 WdfRequestRetrieveOutputMemory et transmet le handle de mémoire à WdfUsbTargetPipeFormatRequestForRead, le pilote ne doit pas terminer la demande d’E/S reçue tant qu’il n’a pas supprimé, réutilisé ou reformaté le nouvel objet de requête créé par le pilote. (WdfUsbTargetPipeFormatRequestForRead 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émentent le nombre de références de l’objet mémoire.)

Après avoir appelé WdfUsbTargetPipeFormatRequestForRead pour mettre en forme une requête d’E/S, le pilote doit appeler WdfRequestSend pour envoyer la requête (de manière synchrone ou asynchrone) à une cible d’E/S.

Les appels multiples à WdfUsbTargetPipeFormatRequestForRead qui utilisent la même requête ne provoquent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire le risque que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd de votre pilote peut appeler WdfRequestCreate pour préallouer un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformat (appeler WdfUsbTargetPipeFormatRequestForRead) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer un STATUS_INSUFFICIENT_RESOURCES valeur de retour d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetPipeFormatRequestForRead 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.)

L’infrastructure définit l’indicateur USBD_SHORT_TRANSFER_OK dans son URB interne. La définition de cet indicateur permet au dernier paquet d’un transfert de données d’être inférieur à la taille maximale du paquet.

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

Pour plus d’informations sur la méthode WdfUsbTargetPipeFormatRequestForRead et les cibles d’E/S USB, consultez 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 EvtIoRead qui transfère une demande de lecture à un canal USB. L’exemple appelle WdfRequestRetrieveOutputMemory pour obtenir la mémoire tampon de sortie de la demande, puis met en forme la demande de lecture 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 
OsrFxEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // First, validate input parameters.
    //
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkReadPipe;
 
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
 
    status = WdfUsbTargetPipeFormatRequestForRead(
                                                  pipe,
                                                  Request,
                                                  reqMemory,
                                                  NULL
                                                  ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   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

Condition requise	Valeur
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)