WdfUsbInterfaceSelectSetting, fonction (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfUsbInterfaceSelectSetting sélectionne un autre paramètre spécifié pour une interface USB spécifiée.

Syntaxe

NTSTATUS WdfUsbInterfaceSelectSetting(
  [in]           WDFUSBINTERFACE                          UsbInterface,
  [in, optional] PWDF_OBJECT_ATTRIBUTES                   PipesAttributes,
  [in]           PWDF_USB_INTERFACE_SELECT_SETTING_PARAMS Params
);

Paramètres

[in] UsbInterface

Handle vers un objet d’interface USB obtenu en appelant WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui spécifie les attributs d’objet pour les objets de canal créés par l’infrastructure pour l’interface. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

Pointeur vers une structure de WDF_USB_INTERFACE_SELECT_SETTING_PARAMS fournie par l’appelant qui contient des paramètres de sélection d’interface.

Valeur retournée

WdfUsbInterfaceSelectSetting retourne la valeur d’achèvement de la cible d’E/S status si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante pour créer un objet de canal.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfUsbInterfaceSelectSetting 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

Une fois que votre pilote a appelé WdfUsbTargetDeviceSelectConfig pour sélectionner une configuration, le pilote peut appeler WdfUsbInterfaceSelectSetting pour sélectionner un autre paramètre pour l’une des interfaces de l’appareil.

Votre pilote peut sélectionner un autre paramètre d’interface en spécifiant un descripteur d’interface USB ou un URB, ou simplement en fournissant un autre paramètre pour l’interface. Dans tous les cas, le pilote doit fournir un handle à un objet d’interface.

Si votre pilote fournit simplement un autre paramètre, l’infrastructure utilise l’objet d’interface pour déterminer l’interface à laquelle appartient le paramètre.

Si votre pilote spécifie un descripteur d’interface ou un URB, l’infrastructure utilise l’interface spécifiée dans le descripteur ou URB.

L’infrastructure crée un objet de canal USB d’infrastructure pour chaque canal associé à l’interface, après avoir supprimé tous les objets de canal que l’infrastructure a pu créer précédemment pour l’interface. Pour obtenir des informations sur les objets de canal d’une interface, votre pilote peut appeler WdfUsbInterfaceGetNumConfiguredPipes et WdfUsbInterfaceGetConfiguredPipe.

Pour plus d’informations sur la méthode WdfUsbInterfaceSelectSetting et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Exemples

L’exemple de code suivant initialise une structure WDF_OBJECT_ATTRIBUTES avec des attributs pour les objets de canal que l’infrastructure va créer. Ensuite, l’exemple initialise une structure WDF_USB_INTERFACE_SELECT_SETTING_PARAMS pour spécifier un autre paramètre 1. Enfin, l’exemple appelle WdfUsbInterfaceSelectSetting pour sélectionner l’autre paramètre et créer des objets de canal pour les canaux de l’interface.

WDF_OBJECT_ATTRIBUTES  pipesAttributes;
WDF_USB_INTERFACE_SELECT_SETTING_PARAMS  selectSettingParams;
NTSTATUS  Status;

WDF_OBJECT_ATTRIBUTES_INIT(&pipesAttributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &pipesAttributes,
                                       MY_PIPE_CONTEXT
                                       );

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING(
                                      &selectSettingParams,
                                      1
                                      );

Status = WdfUsbInterfaceSelectSetting(
                                      UsbInterface,
                                      &pipesAttributes,
                                      &selectSettingParams
                                      );

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), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)