WdfUsbTargetDeviceCreateIsochUrb, fonction (wdfusb.h)

Article
02/27/2024

[S’applique uniquement à KMDF]

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

Syntaxe

NTSTATUS WdfUsbTargetDeviceCreateIsochUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            ULONG                  NumberOfIsochPackets,
  [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 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.

[in] NumberOfIsochPackets

Spécifie le nombre de paquets isochronieux pour lesquels le système alloue de la mémoire dans l’URB.

[out] UrbMemory

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

[out, optional] Urb

Pointeur vers une structure URB qui reçoit l’adresse du nouvel URB isochronieux. L’infrastructure initialise le contenu de la structure URB à zéro. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

WdfUsbTargetDeviceCreateIsochUrb 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 disponible était insuffisante.

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

Remarques

Avant d’appeler WdfUsbTargetDeviceCreateIsochUrb, un pilote doit appeler WdfUsbTargetDeviceCreateWithParameters. En cas de réussite, WdfUsbTargetDeviceCreateIsochUrb retourne un handle à un objet de mémoire framework qui décrit l’URB isochrone nouvellement alloué.

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

En règle générale, un pilote appelle WdfUsbTargetDeviceCreateIsochUrb à partir d’un gestionnaire de requêtes.

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.

Pour plus d’informations, consultez la section Remarques de WdfUsbTargetDeviceCreateUrb.

Exemples

L’exemple de code suivant est basé sur la routine PerformIsochTransfer dans l’exemple de pilote Isorwr. L’exemple appelle WdfUsbTargetDeviceCreateIsochUrb pour allouer un bloc de requête USB isochroné. L’exemple détermine le nombre d’octets requis pour contenir la demande de transfert isochrone, puis configure manuellement l’en-tête URB et les paquets isochroneux dans l’URB. À ce stade, le pilote peut appeler WdfUsbTargetPipeFormatRequestForUrb, comme illustré dans l’exemple dans WdfUsbTargetDeviceCreateUrb.


USBD_PIPE_HANDLE usbdPipeHandle;
ULONG numPackets = UserBufferLength/TransferSizePerFrame;
ULONG urbSize;
PURB urb;  
WDFMEMORY memory;

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

status = WdfUsbTargetDeviceCreateIsochUrb(
                                     pDevContext->WdfUsbTargetDevice,  
                                     &objectAttribs,  
                                     0, 
                                     numPackets, 
                                     &memory,  
                                     NULL  
                                     ); 
 
urb = WdfMemoryGetBuffer(urbMemory, &urbSize); 
urbSize = GET_ISO_URB_SIZE(numPackets);  

usbdPipeHandle = WdfUsbTargetPipeWdmGetPipeHandle(pipe);
urb->UrbIsochronousTransfer.Hdr.Length = GET_ISO_URB_SIZE(numPackets);  
urb->UrbIsochronousTransfer.Hdr.Function = URB_FUNCTION_ISOCH_TRANSFER;  
urb->UrbIsochronousTransfer.PipeHandle = usbdPipeHandle; 

for (packetId = 0; packetId < numberOfPackets; packetId++) {

     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].Offset = xxx;
     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].YYY = yyy;
}

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 de version de la bibliothèque d’infrastructure.)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf)

Voir aussi

WdfUsbTargetDeviceCreateUrb

WdfUsbTargetDeviceCreateWithParameters

Partager via