WdfUsbTargetDeviceCreateWithParameters, fonction (wdfusb.h)
[S’applique à KMDF et UMDF]
La méthode WdfUsbTargetDeviceCreateWithParameters crée un objet d’appareil USB framework pour un objet d’appareil framework spécifié et ouvre l’appareil USB pour les opérations d’E/S. La méthode spécifie également des informations de configuration pour l’objet périphérique USB framework.
Syntaxe
NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
[in] WDFDEVICE Device,
[in] PWDF_USB_DEVICE_CREATE_CONFIG Config,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFUSBDEVICE *UsbDevice
);
Paramètres
[in] Device
Handle vers un objet d’appareil framework.
[in] Config
Pointeur vers une structure WDF_USB_DEVICE_CREATE_CONFIG qui contient des informations de configuration pour l’objet périphérique USB framework.
[in, optional] Attributes
Pointeur vers une structure WDF_OBJECT_ATTRIBUTES fournie par l’appelant qui contient des attributs pour le nouvel objet périphérique USB framework. (Le membre ParentObject de la structure doit avoir la valeur NULL.) Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.
[out] UsbDevice
Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet périphérique USB framework.
Valeur de retour
WdfUsbTargetDeviceCreateWithParameters retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Retourner le code | Description |
|---|---|
|
Le paramètre Config n’est pas la taille correcte. |
|
Il n’y avait pas suffisamment de mémoire pour créer un objet périphérique USB framework. |
|
Un paramètre non valide a été détecté. Pour plus d’informations, consultez la section Remarques. |
|
Une tentative d’obtention des informations de configuration USB a échoué. |
Pour obtenir la liste des autres valeurs de retour que la méthode WdfUsbTargetDeviceCreateWithParameters peut retourner, consultez Framework Object Creation Errors.
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
Windows 8 inclut une nouvelle pile de pilotes USB pour prendre en charge les appareils USB 3.0.
Avant qu’un pilote client basé sur le framework puisse utiliser les nouvelles fonctionnalités de la pile de pilotes USB pour Windows 8, le pilote doit s’inscrire auprès de la pile de pilotes USB sous-jacente chargée par Windows pour l’appareil. Pour inscrire le pilote client, appelez WdfUsbTargetDeviceCreateWithParameters et spécifiez une version de contrat dans la structure WDF_USB_DEVICE_CREATE_CONFIG.
Si le pilote client est destiné à générer, exécuter et utiliser les améliorations et les nouvelles fonctionnalités sur Windows 8, la version du contrat client est USBD_CLIENT_CONTRACT_VERSION_602.
En règle générale, les pilotes appellent WdfUsbTargetDeviceCreateWithParameters à partir d’un EvtDevicePrepareHardware fonction de rappel. Les pilotes peuvent également appeler WdfUsbTargetDeviceCreateWithParameters à partir d’une fonction de rappel EvtDriverDeviceAdd.
Pour plus d’informations sur la façon dont les pilotes clients USB WDM interagissent avec la pile des pilotes USB 3.0, consultez Meilleures pratiques : Utilisation des URI.
Si le pilote appelle WdfUsbTargetDeviceCreateWithParameters pour créer un objet de périphérique USB de framework, le pilote doit créer des URI uniquement en appelant WdfUsbTargetDeviceCreateUrb ou WdfUsbTargetDeviceCreateIsochUrb.
Si vous appelez cette méthode à partir d’un pilote UMDF, vous devez spécifier la directive UmdfDispatcher dans le fichier INF du pilote. Sinon, cette méthode peut retourner STATUS_INVALID_PARAMETER. Pour plus d’informations sur cette directive, consultez Spécification de directives WDF dans les fichiers INF.
Exemples
L’exemple de code suivant fait partie d’une fonction de rappel EvtDevicePrepareHardware qui appelle WdfUsbTargetDeviceCreateWithParameters. L’exemple stocke le handle sur l’objet périphérique USB framework dans l’espace de contexte défini par le pilote.
NTSTATUS
MyEvtDevicePrepareHardware(
IN WDFDEVICE Device,
IN WDFCMRESLIST ResourceList,
IN WDFCMRESLIST ResourceListTranslated
)
{
NTSTATUS status;
PMY_DEVICE_CONTEXT pMyDeviceContext;
WDF_USB_DEVICE_CREATE_CONFIG Config;
pMyDeviceContext = GetDeviceContext(Device);
// If object handle is not NULL, MyEvtDevicePrepareHardware
// was called previously and the handle is still valid.
if (pMyDeviceContext->UsbDevice != NULL) {
return STATUS_SUCCESS;
}
WDF_USB_DEVICE_CREATE_CONFIG_INIT(
&Config,
USBD_CLIENT_CONTRACT_VERSION_602
);
status = WdfUsbTargetDeviceCreateWithParameters(
Device,
&Config,
WDF_NO_OBJECT_ATTRIBUTES,
&pMyDeviceContext->UsbDevice
);
if (!NT_SUCCESS(status)) {
return status;
}
...
}
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| version minimale de KMDF | 1.11 |
| version minimale de UMDF | 2.0 |
| d’en-tête | wdfusb.h (include Wdfusb.h) |
| bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| règles de conformité DDI | DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf) |