WdfUsbTargetDeviceSendUrbSynchronously, fonction (wdfusb.h)

Article
08/08/2023

[S’applique uniquement à KMDF]

La méthode WdfUsbTargetDeviceSendUrbSynchronously envoie une requête USB de manière synchrone à un périphérique USB spécifié, à l’aide de paramètres de requête qui sont décrits par un URB.

Syntaxe

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           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] Request

Handle d’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 les options de la demande. Ce pointeur est facultatif et peut avoir la valeur NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in] Urb

Pointeur vers une structure URB initialisée par l’appelant.

Si le pilote précédemment appelé WdfUsbTargetDeviceCreateWithParameters pour créer UsbDevice, le pilote doit utiliser WdfUsbTargetDeviceCreateUrb ou WdfUsbTargetDeviceCreateIsochUrb pour créer cet URB.

Valeur retournée

WdfUsbTargetDeviceSendUrbSynchronously retourne la valeur d’achèvement de la cible d’E/S status 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_REQUEST	L’IRQL de l’appelant n’était pas valide.
STATUS_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante.
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 WdfUsbTargetDeviceSendUrbSynchronously pour envoyer une demande de transfert de contrôle USB de manière synchrone. Pour envoyer de telles demandes de manière asynchrone, utilisez WdfUsbTargetDeviceFormatRequestForUrb, suivi de WdfRequestSend.

La méthode WdfUsbTargetDeviceSendUrbSynchronously 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 du 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.

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 demande reçue pour le paramètre Request de la méthode WdfUsbTargetDeviceSendUrbSynchronously.

Pour créer et envoyer une nouvelle requête, fournissez un handle de requête NULL pour 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 de requête non NULL ou NULL. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.

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

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

Exemples

L’exemple de code suivant initialise une structure URB et appelle WdfUsbTargetDeviceSendUrbSynchronously.

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)