WdfUsbTargetDeviceCreateWithParameters, fonction (wdfusb.h)
[S’applique à KMDF et UMDF]
La méthode WdfUsbTargetDeviceCreateWithParameters crée un objet de périphérique USB d’infrastructure pour un objet de périphérique d’infrastructure spécifié et ouvre le périphérique 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 du 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 pour un objet d’appareil d’infrastructure.
[in] Config
Pointeur vers une structure WDF_USB_DEVICE_CREATE_CONFIG qui contient des informations de configuration pour l’objet périphérique USB du framework.
[in, optional] Attributes
Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES fournie par l’appelant qui contient des attributs pour le nouvel objet périphérique USB du framework. (Le membre ParentObject de la structure doit être 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 du framework.
Valeur retournée
WdfUsbTargetDeviceCreateWithParameters retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
Le paramètre Config n’a pas la taille correcte. |
|
La mémoire était insuffisante pour créer un nouvel objet périphérique USB d’infrastructure. |
|
Un paramètre non valide a été détecté. Pour plus d'informations, consultez la section Notes. |
|
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 Erreurs de création d’objets framework.
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
Windows 8 comprend une nouvelle pile de pilotes USB pour prendre en charge les périphériques USB 3.0.
Avant qu’un pilote client basé sur l’infrastructure 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 le périphérique. 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’une fonction de rappel EvtDevicePrepareHardware . 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 de pilotes USB 3.0, consultez Meilleures pratiques : utilisation d’URBs.
Si le pilote appelle WdfUsbTargetDeviceCreateWithParameters pour créer un objet de périphérique USB d’infrastructure, le pilote doit créer des URBs 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 dans l’objet périphérique USB du framework dans l’espace contextuel 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;
}
...
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.11 |
| 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), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf) |