fonction USBD_UrbAllocate (usbdlib.h)

Article
02/07/2025

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

Handle USBD récupéré par le pilote client dans 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 de retour

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

Les valeurs possibles incluent, mais pas uniquement, STATUS_INVALID_PARAMETER, ce qui indique que l’appelant est passé en 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 les allouent sur la pile.

Le pilote client ne doit pas utiliser USBD_UrbAllocate,

Pour allouer une URB qui a une longueur variable, telle qu’une URB pour un transfert isochrone. 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ée 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 de Comment envoyer unURB .

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;

}

Exigences

Exigence	Valeur
client minimum 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	Bureau
d’en-tête	usbdlib.h
bibliothèque	Usbdex.lib
IRQL	DISPATCH_LEVEL

Voir aussi

allocation et génération d’URBs

l’envoi de requêtes à un périphérique USB

USBD_UrbFree

Partager via