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 :

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

Voir aussi

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate