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 pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.
[in] Request
Handle pour un objet de requête d’infrastructure. 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] TransferMemory
Handle vers un objet de mémoire d’infrastructure 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.
[in, optional] TransferOffset
Pointeur vers une structure de WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octets et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse et la longueur de début, dans la mémoire tampon spécifiée par TransferMemory . Si ce pointeur a la valeur NULL, l’infrastructure utilise la mémoire tampon entière.
Valeur retournée
WdfUsbTargetDeviceFormatRequestForControlTransfer retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
Un paramètre non valide a été détecté. |
|
La mémoire disponible était insuffisante. |
|
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. |
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 WdfUsbTargetDeviceFormatRequestForControlTransfer, suivi 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 manière synchrone.
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 de la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer.
-
Utilisez la mémoire tampon d’entrée ou de sortie de la requête reçue pour le paramètre TransferMemory .
Le pilote doit appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle pour un objet de mémoire du 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 de votre 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 TransferMemory de la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer.
Votre pilote doit spécifier cet espace de mémoire 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, 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.
Les appels multiples à WdfUsbTargetDeviceFormatRequestForControlTransfer qui utilisent la même requête ne provoquent 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 de votre pilote peut appeler WdfRequestCreate pour préallouer 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.)
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 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 « get status ». 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);
}
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 | <=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) |