WdfUsbTargetDeviceFormatRequestForControlTransfer, fonction (wdfusb.h)
[S’applique à KMDF et UMDF]
La méthode WdfUsbTargetDeviceFormatRequestForControlTransfer génère une demande de transfert de contrôle USB, mais elle n’envoie pas la requête.
Syntaxe
NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request,
[in] PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional] WDFMEMORY TransferMemory,
[in, optional] PWDFMEMORY_OFFSET TransferOffset
);
Paramètres
[in] UsbDevice
Handle vers un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.
[in] Request
Handle vers un objet de requête de framework. Pour plus d’informations, consultez la section Remarques suivante.
[in] SetupPacket
Pointeur vers une structure WDF_USB_CONTROL_SETUP_PACKET allouée par l’appelant qui décrit le transfert de contrôle.
[in, optional] TransferMemory
Handle vers un objet de mémoire de framework qui décrit une entrée ou une mémoire tampon 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 Remarques suivante.
[in, optional] TransferOffset
Pointeur vers une structure WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse et la longueur de début, dans la mémoire tampon qui TransferMemory spécifie. Si ce pointeur est NULL, l’infrastructure utilise l’intégralité de la mémoire tampon.
Valeur de retour
WdfUsbTargetDeviceFormatRequestForControlTransfer retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Retourner le code | Description |
|---|---|
|
Un paramètre non valide a été détecté. |
|
Mémoire insuffisante disponible. |
|
Un descripteur de mémoire non valide a été spécifié ou la requête d’E/S spécifiée a déjà été mise en file d’attente vers une cible d’E/S. |
Cette méthode peut également retourner d’autres valeurs NTSTATUS .
Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.
Remarques
Utilisez WdfUsbTargetDeviceFormatRequestForControlTransfer, suivie de WdfRequestSend, pour envoyer une demande de transfert de contrôle USB de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetDeviceSendControlTransferSynchronously pour envoyer une requête de façon synchrone.
Vous pouvez transférer une demande d’E/S reçue par votre pilote 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, éventuellement un espace 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 de WdfUsbTargetDeviceFormatRequestForControlTransfer de la méthode Request.
-
Utilisez la mémoire tampon d’entrée ou de sortie de la demande reçue pour le paramètre TransferMemory.
Le pilote doit appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle vers un objet mémoire de framework qui représente la mémoire tampon d’entrée ou de sortie de la requête, et utiliser ce handle comme valeur pour TransferMemory.
-
Créez un objet de requête et fournissez son handle pour le paramètre Request de la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer.
Appelez WdfRequestCreate pour préallouer un ou plusieurs objets de requête. Vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. La fonction de rappel EvtDriverDeviceAdd pilote peut préallouer des objets de requête pour un appareil.
-
Fournissez de l’espace tampon et fournissez le handle de la mémoire tampon pour le paramètre WdfUsbTargetDeviceFormatRequestForControlTransfer de la méthode TransferMemory.
Votre pilote doit spécifier cet espace tampon en tant que handle WDFMEMORY pour la mémoire gérée par l’infrastructure. Votre pilote peut effectuer l’une des opérations suivantes :
- Appelez WdfMemoryCreate ou WdfMemoryCreatePreallocated pour créer une mémoire tampon de mémoire tampon, si vous souhaitez que le pilote passe une nouvelle mémoire tampon à la cible d’E/S.
- Appelez WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle à l’objet mémoire qui représente la mémoire tampon d’une requête d’E/S reçue, si vous souhaitez que le pilote passe le contenu de cette mémoire tampon à la cible d’E/S.
Plusieurs appels à WdfUsbTargetDeviceFormatRequestForControlTransfer qui utilisent la même requête n’entraînent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire le risque que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd evtDriverDeviceAdd peut appeler WdfRequestCreate pour prélocaliser un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformat (appeler WdfUsbTargetDeviceFormatRequestForControlTransfer) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une valeur de retour STATUS_INSUFFICIENT_RESOURCES d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetDeviceFormatRequestForControlTransfer pour l’objet de requête réutilisé retournent STATUS_SUCCESS, si les valeurs de paramètre ne changent pas. (Si le pilote n’appelle pas la même méthode de mise en forme de requête chaque fois, des ressources supplémentaires peuvent être allouées.)
Le framework 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 des paquets.
Pour plus d’informations sur l’obtention des informations d’état une fois qu’une demande d’E/S est terminée, consultez Obtention des informations d’achèvement.
Pour plus d’informations sur la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer et les cibles d’E/S USB, consultez cibles d’E/S USB.
Exemples
L’exemple de code suivant crée un objet de requête et un objet mémoire, puis initialise une structure WDF_USB_CONTROL_SETUP_PACKET pour un transfert de contrôle « obtenir l’état ». Ensuite, l’exemple appelle WdfUsbTargetDeviceFormatRequestForControlTransfer pour mettre en forme la requête. Ensuite, l’exemple définit une fonction de rappel CompletionRoutine et envoie la requête à une cible d’E/S.
WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfRequestCreate(
&attributes,
WdfUsbTargetDeviceGetIoTarget(
UsbTargetDevice,
&request
)
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
sizeof(USHORT),
&memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
&packet,
BmRequestToDevice,
0
);
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
UsbTargetDevice,
request,
&packet,
memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL
);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| version minimale de KMDF | 1.0 |
| version minimale de UMDF | 2.0 |
| d’en-tête | wdfusb.h (include Wdfusb.h) |
| bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| règles de conformité DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |