WdfUsbTargetDeviceCreate, fonction (wdfusb.h)
[S’applique à KMDF et UMDF]
La méthode WdfUsbTargetDeviceCreate 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.
Syntaxe
NTSTATUS WdfUsbTargetDeviceCreate(
[in] WDFDEVICE Device,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFUSBDEVICE *UsbDevice
);
Paramètres
[in] Device
Handle pour un objet d’appareil d’infrastructure.
[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. (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
WdfUsbTargetDeviceCreate 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 était insuffisante pour créer un nouvel objet de périphérique USB. |
|
Une tentative d’obtention des informations de configuration USB a échoué. |
Pour obtenir la liste des autres valeurs de retour que la méthode WdfUsbTargetDeviceCreate 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
Un pilote qui utilise une cible d’E/S USB doit appeler WdfUsbTargetDeviceCreate une fois que son appareil est entré dans son état de fonctionnement (D0). En règle générale, un pilote appelle WdfUsbTargetDeviceCreate à partir de sa fonction de rappel EvtDevicePrepareHardware . (Le pilote ne peut pas appeler WdfUsbTargetDeviceCreate à partir de sa fonction de rappel EvtDriverDeviceAdd .)
WdfUsbTargetDeviceCreate obtient le descripteur de périphérique USB et le premier descripteur de configuration USB de l’appareil et les stocke. Il crée également un objet d’interface USB d’infrastructure pour chaque interface de la première configuration de l’appareil. Pour déterminer le nombre d’interfaces prises en charge par la configuration, le pilote peut appeler WdfUsbTargetDeviceGetNumInterfaces.
Après avoir appelé WdfUsbTargetDeviceCreate, votre pilote peut appeler des méthodes d’objet de périphérique USB de framework supplémentaires.
Le parent de chaque objet de périphérique USB est l’objet pilote d’infrastructure du pilote. Le pilote ne peut pas modifier ce parent, et le membre ParentObject ou la structure WDF_OBJECT_ATTRIBUTES doit avoir la valeur NULL.
Pour plus d’informations sur la méthode WdfUsbTargetDeviceCreate et les cibles d’E/S USB, consultez Cibles d’E/S USB.
Exemples
L’exemple de code suivant fait partie d’une fonction de rappel EvtDevicePrepareHardware qui appelle WdfUsbTargetDeviceCreate. L’exemple stocke le handle de l’objet de périphérique USB 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;
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;
}
status = WdfUsbTargetDeviceCreate(
Device,
WDF_NO_OBJECT_ATTRIBUTES,
&pMyDeviceContext->UsbDevice
);
if (!NT_SUCCESS(status)) {
return status;
}
...
}
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 | PASSIVE_LEVEL |
| Règles de conformité DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |