WdfUsbTargetDeviceSendControlTransferSynchronously, fonction (wdfusb.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceSendControlTransferSynchronously génère une demande de transfert de contrôle USB et l’envoie de manière synchrone à une cible d’E/S.

Syntaxe

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

Paramètres

[in] UsbDevice

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

[in, optional] Request

Handle pour un objet de requête d’infrastructure. Ce paramètre est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] RequestOptions

Pointeur vers une structure de WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie des options pour la demande. Ce pointeur est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in] SetupPacket

Pointeur vers une structure de WDF_USB_CONTROL_SETUP_PACKET allouée à l’appelant qui décrit le transfert de contrôle.

[in, optional] MemoryDescriptor

Pointeur vers une structure de WDF_MEMORY_DESCRIPTOR allouée à l’appelant qui décrit une mémoire tampon d’entrée ou de sortie, en fonction de la commande spécifique à l’appareil. Ce pointeur est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[out, optional] BytesTransferred

Pointeur vers un emplacement qui reçoit le nombre d’octets transférés. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

WdfUsbTargetDeviceSendControlTransferSynchronously retourne la valeur d’achèvement status cible d’E/S 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_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante.
STATUS_INVALID_DEVICE_REQUEST	Un descripteur de mémoire non valide a été spécifié ou la demande d’E/S spécifiée était déjà mise en file d’attente vers une cible d’E/S.
STATUS_IO_TIMEOUT	Le pilote a fourni une valeur de délai d’attente et la demande n’a pas été effectuée dans le délai imparti.

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

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Utilisez la méthode WdfUsbTargetDeviceSendControlTransferSynchronously pour envoyer une demande de transfert de contrôle USB de manière synchrone. Pour envoyer de telles demandes de manière asynchrone, utilisez WdfUsbTargetDeviceFormatRequestForControlTransfer, suivi de WdfRequestSend.

La méthode WdfUsbTargetDeviceSendControlTransferSynchronously ne retourne pas tant que la requête n’est pas terminée, sauf si le pilote fournit une valeur de délai d’attente dans la structure WDF_REQUEST_SEND_OPTIONS vers laquelle pointe le paramètre RequestOptions , ou si une erreur est détectée.

Vous pouvez transférer une demande d’E/S que votre pilote a reçue dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande. Dans les deux cas, l’infrastructure nécessite un objet de requête et, selon le type de transfert de contrôle, peut-être un espace de mémoire tampon.

Pour transférer une demande d’E/S reçue par votre pilote dans une file d’attente d’E/S :

Spécifiez le handle de la requête reçue pour le paramètre Request .
Utilisez la mémoire tampon d’entrée ou de sortie de la requête reçue pour le paramètre MemoryDescriptor .
Le pilote peut appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle pour un objet de mémoire d’infrastructure qui représente la mémoire tampon d’entrée ou de sortie de la requête, puis placer ce handle dans la structure WDF_MEMORY_DESCRIPTOR que le pilote fournit pour le paramètre MemoryDescriptor .

Pour créer et envoyer une nouvelle demande :

Fournissez un handle de requête NULL dans le paramètre Request , ou créez un objet de requête et fournissez son handle :
- Si vous fournissez un handle de requête NULL , l’infrastructure utilise un objet de requête interne. Cette technique est simple à utiliser, mais le pilote ne peut pas annuler la demande.
- Si vous appelez WdfRequestCreate pour créer un ou plusieurs objets de requête, vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. Cette technique permet à la fonction de rappel EvtDriverDeviceAdd de votre pilote de préallouer des objets de requête pour un appareil. En outre, un autre thread de pilote peut appeler WdfRequestCancelSentRequest pour annuler la demande, si nécessaire.
Votre pilote peut spécifier un paramètre RequestOptions non NULL, que le pilote fournisse un paramètre non NULL ou un paramètre de requêteNULL. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.
Fournir de l’espace tampon pour le paramètre MemoryDescriptor de la méthode WdfUsbTargetDeviceSendControlTransferSynchronously.
Votre pilote peut spécifier cet espace de mémoire tampon en tant que mémoire tampon allouée localement, en tant que handle WDFMEMORY ou en tant que MDL. Vous pouvez utiliser la méthode la plus pratique.

Si nécessaire, l’infrastructure convertit la description de la mémoire tampon en une description correcte pour la méthode de la cible d’E/S pour accéder aux mémoires tampons de données.

Les techniques suivantes sont disponibles :
- Fournir une mémoire tampon locale
  Étant donné que WdfUsbTargetDeviceSendControlTransferSynchronously gère les demandes d’E/S de manière synchrone, le pilote peut créer des mémoires tampons de requête qui sont locales à la routine appelante, comme illustré dans l’exemple de code suivant.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Fournir un handle WDFMEMORY
  Appelez WdfMemoryCreate ou WdfMemoryCreatePreallocated pour obtenir un handle pour la mémoire gérée par l’infrastructure, comme indiqué dans l’exemple de code suivant.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
WDFMEMORY  memoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &memoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                  memoryHandle,
                                  NULL);
```
  Le pilote peut également appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle à un objet mémoire du framework qui représente la mémoire tampon d’une demande d’E/S reçue, si vous souhaitez que le pilote passe le contenu de cette mémoire tampon à la cible d’E/S. Le pilote ne doit pas terminer la demande d’E/S reçue tant que la nouvelle requête que WdfUsbTargetDeviceSendControlTransferSynchronously envoie à la cible d’E/S n’a pas été supprimée, réutilisée ou reformatée. (WdfUsbTargetDeviceSendControlTransferSynchronously incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou la reformatage d’un objet de requête décrémentent le nombre de références de l’objet mémoire.)
- Fournir un MDL
  Les pilotes peuvent obtenir des DLL associées à une demande d’E/S reçue en appelant WdfRequestRetrieveInputWdmMdl ou WdfRequestRetrieveOutputWdmMdl.

L’infrastructure définit l’indicateur USBD_SHORT_TRANSFER_OK dans son URB interne. La définition de cet indicateur permet au dernier paquet d’un transfert de données d’être inférieur à la taille maximale du paquet.

Pour plus d’informations sur l’obtention d’informations status après la fin d’une demande d’E/S, consultez Obtention d’informations d’achèvement.

Pour plus d’informations sur la méthode WdfUsbTargetDeviceSendControlTransferSynchronously et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Exemples

L’exemple de code suivant initialise une structure WDF_USB_CONTROL_SETUP_PACKET , puis appelle WdfUsbTargetDeviceSendControlTransferSynchronously pour envoyer un transfert de contrôle spécifique au fournisseur.

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)