WdfUsbTargetPipeFormatRequestForUrb, fonction (wdfusb.h)

[S’applique à KMDF uniquement]

La méthode WdfUsbTargetPipeFormatRequestForUrb génère une requête USB pour un canal USB spécifié, à l’aide des paramètres de requête décrits par un URB spécifié, mais elle 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 pour 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 a 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 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 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 retournée

WdfUsbTargetPipeFormatRequestForUrb retourne la valeur d’achèvement status de la cible d’E/S si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

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 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 que votre pilote a reçue dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande.

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 demande 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 WdfUsbTargetPipeFormatRequestForUrb. Vous pouvez réutiliser l’objet de requête en appelant WdfRequestReuse, afin que la fonction de rappel EvtDriverDeviceAdd de votre pilote puisse 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 demande (de manière synchrone ou asynchrone) à une cible d’E/S.

Les appels multiples à 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 un STATUS_INSUFFICIENT_RESOURCES valeur de retour 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 de requête à chaque fois, des ressources supplémentaires peuvent être allouées.)

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

Voir aussi

WDFMEMORY_OFFSET

WdfMemoryCreate

WdfMemoryGetBuffer

WdfRequestCompleteWithInformation

WdfRequestSend

WdfRequestSetCompletionRoutine

WdfUsbInterfaceGetConfiguredPipe