WdfUsbTargetDeviceCreateUrb, fonction (wdfusb.h)

Article
02/07/2025

[S’applique uniquement à KMDF]

La méthode WdfUsbTargetDeviceCreateUrb alloue un bloc de requête USB (URB).

Syntaxe

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

Paramètres

[in] UsbDevice

Handle vers un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Attributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES fournie par l’appelant qui contient des attributs pour le nouvel objet mémoire. Si le pilote fournit ce paramètre, le membre ParentObject de la structure doit être un objet de périphérique USB (WDFUSBDEVICE) ou un objet de requête (WDFREQUEST) créé par l’infrastructure, ou tout objet dont la chaîne de parents conduit à l’un de ces types. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

Pointeur vers un emplacement typé WDFMEMORY qui reçoit un handle vers un objet mémoire de framework.

[out, optional] Urb

Pointeur vers une structure URB qui reçoit l’adresse de l’URB nouvellement allouée. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

WdfUsbTargetDeviceCreateUrb retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Retourner le code	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INVALID_DEVICE_STATE	Le pilote n’a pas spécifié de version de contrat client lorsqu’il a appelé WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante pour créer une nouvelle URB.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Remarques

Avant d’appeler WdfUsbTargetDeviceCreateUrb, un pilote doit appeler WdfUsbTargetDeviceCreateWithParameters. Si elle réussit, WdfUsbTargetDeviceCreateUrb retourne un handle à un objet mémoire de framework qui décrit l’URB nouvellement alloué. En règle générale, un pilote appelle WdfUsbTargetDeviceCreateUrb à partir d’un gestionnaire de requêtes .

Un pilote peut appeler WdfUsbTargetDeviceCreateUrb pour allouer une structure URB avant d’appeler WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb est similaire en opération à WdfMemoryCreate. Les deux méthodes allouent un objet mémoire de framework, et les deux méthodes fournissent également la possibilité de recevoir la mémoire tampon (dans ce cas, l’URB) associée à l’objet mémoire. Dans les deux cas, l’appelant peut également récupérer la mémoire tampon ultérieurement en appelant WdfMemoryGetBuffer.

Si le pilote fournit un paramètre Urb lorsqu’il appelle WdfUsbTargetDeviceCreateUrb, vous pouvez mettre en forme l’URB manuellement ou en appelant les routines UsbBuildXxx.

L’objet mémoire et sa mémoire tampon sont supprimés lorsque l’objet parent est supprimé. Un pilote peut également supprimer un objet mémoire et sa mémoire tampon en appelant WdfObjectDelete.

Exemples

L’exemple de code suivant déclare un objet de mémoire de framework. L’exemple appelle WdfUsbTargetDeviceCreateUrb pour allouer un bloc de requête USB, puis appelle WdfUsbTargetDeviceFormatRequestForUrb pour mettre en forme une requête qui utilise le contenu de la structure URB. Enfin, l’exemple enregistre une fonction de rappel CompletionRoutine et envoie la requête à une cible d’E/S.

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista
plateforme cible	Universel
version minimale de KMDF	1.11
d’en-tête	wdfusb.h (include Wdfusb.h)
bibliothèque	Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
IRQL	<=DISPATCH_LEVEL
règles de conformité DDI	DriverCreate(kmdf)

Voir aussi

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

Partager via