USBD_UrbAllocate fonction (usbdlib.h)

La routine USBD_UrbAllocate alloue un bloc de requête USB (URB).

Syntaxe

NTSTATUS USBD_UrbAllocate(
  [in]  USBD_HANDLE USBDHandle,
  [out] PURB        *Urb
);

Paramètres

[in] USBDHandle

Poignée USBD récupérée par le pilote client lors d’un appel précédent à la routine USBD_CreateHandle .

[out] Urb

Pointeur vers la structure URB nouvellement allouée. Tous les membres de la structure sont définis sur zéro. Le pilote client doit libérer l’URB lorsque le pilote a terminé de l’utiliser en appelant USBD_UrbFree.

Valeur retournée

La routine USBD_UrbAllocate retourne STATUS_SUCCESS si la demande réussit. Sinon, USBD_UrbAllocate définit Urb sur NULL et retourne un code d’échec.

Les valeurs possibles incluent, sans s’y limiter, STATUS_INVALID_PARAMETER, qui indique que l’appelant a passé la valeur NULL à USBDHandle ou Urb.

Remarques

La routine USBD_UrbAllocate permet à la pile de pilotes USB sous-jacente d’allouer un contexte URB opaque pour l’URB. En utilisant le contexte URB, la pile de pilotes USB peut traiter les requêtes de manière plus efficace et fiable. Ces optimisations sont fournies par la pile de pilotes USB 3.0 incluse dans Windows 8. Le pilote client ne peut pas accéder au contexte URB ; le contexte est utilisé en interne par le pilote de bus.

Quelle que soit la version du protocole USB du contrôleur hôte, la pile de pilotes USB sous-jacente, le système d’exploitation cible, le pilote client doit toujours appeler USBD_UrbAllocate pour allouer une structure URB . USBD_UrbAllocate remplace les mécanismes d’allocation antérieurs, tels que ExAllocatePoolWithTag, ou leur allocation sur la pile.

Le pilote client ne doit pas utiliser USBD_UrbAllocate,

• Pour allouer un URB dont la longueur est variable, comme un URB pour un transfert isochronieux. Au lieu de cela, le pilote client doit appeler USBD_IsochUrbAllocate.
• Si le système d’exploitation cible est Windows XP avec Service Pack 2 (SP2) ou une version antérieure de Windows.

Pour plus d’informations sur les routines de remplacement, consultez Allocation et création d’URBs.

Vous devez appeler USBD_UrbFree pour libérer l’URB alloué par USBD_UrbAllocate.

Exemples

L’exemple de code suivant montre comment allouer, envoyer et libérer un URB. L’exemple envoie l’URB de manière synchrone. Pour l’implémentation de la fonction SubmitUrbSync, consultez l’exemple de section dans Comment envoyer un URB.

NTSTATUS CreateandSubmitURBSynchronously (
    _In_ USBD_HANDLE USBDHandle 
{
    PURB    Urb = NULL;

    NTSTATUS status;

    status = USBD_UrbAllocate(USBDHandle, &Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    //Format the URB for the request. Not Shown.
    status = BuildURBForBulkTransfer (Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    status = SubmitUrbSync( TargetDeviceObject,
        Urb)  

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

CreateandSubmitURBExit:

    if (Urb)
    {
        USBD_UrbFree( USBDHandle, Urb); 
    }

    return status;

}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Nécessite WDK pour Windows 8. Cible Windows Vista et les versions ultérieures du système d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	usbdlib.h
Bibliothèque	Usbdex.lib
IRQL	DISPATCH_LEVEL

Voir aussi

Allocation et génération d’URBs

Envoi de requêtes à un périphérique USB

USBD_UrbFree