WdfUsbTargetDeviceSelectConfig, fonction (wdfusb.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceSelectConfig sélectionne une configuration USB pour un appareil ou le déconfigure.

Syntaxe

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

Paramètres

[in] UsbDevice

Handle pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in, optional] PipeAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée à l’appelant qui contient des attributs pour les nouveaux objets de canal USB d’infrastructure que l’infrastructure crée pour les interfaces de l’appareil. Pour les pilotes KMDF, ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES. Les pilotes UMDF doivent définir ce paramètre sur NULL.

[in, out] Params

Pointeur vers une structure de WDF_USB_DEVICE_SELECT_CONFIG_PARAMS allouée à l’appelant que l’appelant et l’infrastructure utilisent pour spécifier les paramètres de configuration.

Valeur retournée

WdfUsbTargetDeviceSelectConfig 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_INFO_LENGTH_MISMATCH	Le membre Size de la structure WDF_USB_DEVICE_SELECT_CONFIG_PARAMS vers laquelle Params pointe était incorrect.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer une mémoire tampon.
STATUS_NOT_SUPPORTED	L’infrastructure retourne cette valeur si un pilote UMDF appelle WdfUsbTargetDeviceSelectConfig avec params->Type défini sur l’un des éléments suivants : WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Pour plus d’informations, consultez WdfUsbTargetDeviceSelectConfigType.

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

Votre pilote peut sélectionner une configuration de périphérique à l’aide d’une structure de WDF_USB_DEVICE_SELECT_CONFIG_PARAMS pour spécifier des descripteurs USB, un URB ou des poignées pour l’infrastructure d’objets d’interface USB.

L’infrastructure crée un objet de canal USB d’infrastructure pour chaque canal associé à chaque interface de la configuration, après avoir supprimé tous les objets de canal que l’infrastructure a pu créer précédemment pour la configuration. L’infrastructure utilise un autre paramètre zéro pour chaque interface, sauf si le pilote spécifie un autre paramètre.

Pour obtenir des informations sur les objets de canal d’une interface, le pilote peut appeler WdfUsbInterfaceGetNumConfiguredPipes et WdfUsbInterfaceGetConfiguredPipe.

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

Attention

Vous pouvez utiliser WdfUsbTargetDeviceSelectConfig pour sélectionner uniquement la première configuration USB répertoriée dans la liste des descripteurs, mais vous pouvez sélectionner plusieurs interfaces dans cette configuration unique.

Exemples

L’exemple de code suivant sélectionne une configuration avec une seule interface spécifiée.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

L’exemple de code suivant sélectionne une configuration avec plusieurs interfaces, en utilisant un autre paramètre zéro sur toutes les interfaces. Cet exemple s’applique uniquement aux pilotes KMDF.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    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), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)