WdfUsbInterfaceSelectSetting, fonction (wdfusb.h)

Article
02/07/2025

[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 WDF_USB_INTERFACE_SELECT_SETTING_PARAMS fournie par l’appelant qui contient des paramètres de sélection d’interface.

Valeur de retour

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

Retourner le code	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 Framework Object Creation Errors.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Une vérification de bogue 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 le paramètre de remplacement d’une interface en spécifiant un descripteur d’interface USB ou un URB, ou en fournissant simplement 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 l’URB.

L’infrastructure crée un objet de canal USB d’infrastructure pour chaque canal associé à l’interface, après avoir supprimé 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 créés par l’infrastructure. Ensuite, l’exemple initialise une structure de WDF_USB_INTERFACE_SELECT_SETTING_PARAMS pour spécifier un autre paramètre 1. Enfin, l’exemple appelle WdfUsbInterfaceSelectSetting pour sélectionner le paramètre de remplacement 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
                                      );

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfusb.h (include 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)