WdfUsbTargetDeviceCreateUrb, fonction (wdfusb.h)

Article
02/29/2024

[S’applique à KMDF uniquement]

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 pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Attributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES fournie par l’appelant qui contient des attributs pour le nouvel objet de 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 de type WDFMEMORY qui reçoit un handle vers un objet mémoire d’infrastructure.

[out, optional] Urb

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

Valeur retournée

WdfUsbTargetDeviceCreateUrb retourne STATUS_SUCCESS 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_INVALID_DEVICE_STATE	Le pilote n’a pas spécifié de version de contrat client quand il a appelé WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante pour créer un URB.

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

Remarques

Avant d’appeler WdfUsbTargetDeviceCreateUrb, un pilote doit appeler WdfUsbTargetDeviceCreateWithParameters. En cas de réussite, WdfUsbTargetDeviceCreateUrb retourne un handle à un objet de 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 à WdfMemoryCreate. Les deux méthodes allouent un objet de mémoire framework, et les deux méthodes offrent é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 inscrit une fonction de rappel CompletionRoutine et envoie la demande à 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);
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Plateforme cible	Universal
Version KMDF minimale	1.11
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf)

Voir aussi

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

Partager via