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 :

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

Voir aussi

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces