WdfUsbTargetPipeFormatRequestForUrb, fonction (wdfusb.h)

[S’applique uniquement à KMDF]

La méthode WdfUsbTargetPipeFormatRequestForUrb génère une requête USB pour un canal USB spécifié, à l’aide de paramètres de requête décrits par un URB spécifié, mais il n’envoie pas la requête.

Syntaxe

NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
                 WDFUSBPIPE        PIPE,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Paramètres

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] UrbMemory

Handle vers un objet de mémoire d’infrastructure qui contient une structure URB .

Si le pilote précédemment appelé WdfUsbTargetDeviceCreateWithParameters pour créer UsbDevice, le pilote doit utiliser WdfUsbTargetDeviceCreateUrb ou WdfUsbTargetDeviceCreateIsochUrb pour créer l’URB contenu dans cet objet mémoire.

[in, optional] UrbMemoryOffset

Pointeur vers une structure 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 de début de l’URB dans la mémoire spécifiée par UrbMemory . Si ce pointeur a la valeur NULL, l’URB se trouve au début de la mémoire UrbMemory .

Valeur de retour

WdfUsbTargetPipeFormatRequestForUrb retourne la valeur d’état d’achèvement de la cible d’E/S 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
Mémoire insuffisante disponible.
STATUS_INTEGER_OVERFLOW
Décalage spécifié par le paramètre UsbMemoryOffset non valide.
STATUS_REQUEST_NOT_ACCEPTED
Le paquet de demande d’E/S (IRP) représenté par 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.

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

Remarques

Utilisez WdfUsbTargetPipeFormatRequestForUrb, suivi de WdfRequestSend, pour envoyer une requête USB de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetPipeSendUrbSynchronously pour envoyer une requête de manière synchrone.

L’infrastructure n’examine pas la requête USB. Si la demande change l’état du canal USB, l’infrastructure n’est pas au courant de la modification.

Vous pouvez transférer une demande d’E/S reçue par votre pilote dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande.

Pour transférer une requête 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 WdfUsbTargetPipeFormatRequestForUrb.

Pour créer une demande d’E/S, appelez WdfRequestCreate pour préallouer un objet de requête. Fournissez le handle de requête pour le paramètre Request de la méthode Request de la méthode WdfUsbTargetPipeFormatRequestForUrb. Vous pouvez réutiliser l’objet de requête en appelant WdfRequestReuse. Par conséquent, la fonction de rappel EvtDriverDeviceAdd de votre pilote peut préallouer des objets de requête pour un appareil.

Après avoir appelé WdfUsbTargetPipeFormatRequestForUrb 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.

Plusieurs appels à WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une valeur de retour STATUS_INSUFFICIENT_RESOURCES à partir d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetPipeFormatRequestForUrb 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 des requêtes chaque fois, des ressources supplémentaires peuvent être allouées.)

Pour plus d’informations sur l’obtention des informations d’état une fois qu’une demande d’E/S est terminée, consultez Obtention des informations d’achèvement.

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

Exemples

L’exemple de code suivant crée un objet mémoire qui représente un URB. Ensuite, l’exemple initialise l’URB, met en forme une requête USB qui contient l’URB, inscrit une fonction de rappel CompletionRoutine et envoie la requête.

URB  urb;
PURB  pUrb = NULL;
WDFMEMORY  urbMemory
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER),
                         &urbMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

pUrb = WdfMemoryGetBuffer(
                          urbMemory,
                          NULL
                          );

pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeFormatRequestForUrb(
                                             pipe,
                                             Request,
                                             urbMemory,
                                             NULL
                                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}
WdfRequestSetCompletionRoutine(
                               Request,
                               UrbCompletionRoutine,
                               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
En-tête wdfusb.h (include Wdfusb.h)
Bibliothèque Wdf01000.sys (voir Gestion des versions de la bibliothèque Framework.)
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

WDFMEMORY_OFFSET

WdfMemoryCreate

WdfMemoryGetBuffer

WdfRequestCompleteWithInformation

WdfRequestSend

WdfRequestSetCompletionRoutine

WdfUsbInterfaceGetConfiguredPipe