Funzione WdfUsbInterfaceSelectSetting (wdfusb.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfUsbInterfaceSelectSetting seleziona un'impostazione alternativa specificata per un'interfaccia USB specificata.

Sintassi

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

Parametri

[in] UsbInterface

Handle a un oggetto interfaccia USB ottenuto chiamando WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che specifica gli attributi dell'oggetto per gli oggetti pipe creati dal framework per l'interfaccia. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

Puntatore a una struttura di WDF_USB_INTERFACE_SELECT_SETTING_PARAMS fornita dal chiamante che contiene parametri di selezione dell'interfaccia.

Valore restituito

WdfUsbInterfaceSelectSetting restituisce il valore di stato di completamento della destinazione di I/O se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente per creare un nuovo oggetto pipe.

Per un elenco di altri valori restituiti che il metodo WdfUsbInterfaceSelectSetting potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Dopo che il driver chiama WdfUsbTargetDeviceSelectConfig per selezionare una configurazione, il driver può chiamare WdfUsbInterfaceSelectSetting per selezionare un'impostazione alternativa per una delle interfacce del dispositivo.

Il driver può selezionare l'impostazione alternativa di un'interfaccia specificando un descrittore dell'interfaccia USB o un ISTANZA oppure fornendo semplicemente un'impostazione alternativa per l'interfaccia. In tutti i casi, il driver deve fornire un handle a un oggetto interfaccia.

Se il driver fornisce solo un'impostazione alternativa, il framework usa l'oggetto interfaccia per determinare l'interfaccia a cui appartiene l'impostazione.

Se il driver specifica un descrittore di interfaccia o UN FRAMEWORK, il framework usa l'interfaccia specificata nel descrittore o NELL'OGGETTO.

Il framework crea un oggetto pipe USB framework per ogni pipe associata all'interfaccia, dopo aver eliminato tutti gli oggetti pipe che il framework potrebbe aver creato in precedenza per l'interfaccia. Per ottenere informazioni sugli oggetti pipe di un'interfaccia, il driver può chiamare WdfUsbInterfaceGetNumConfiguredPipes e WdfUsbInterfaceGetConfiguredPipe.

Per altre informazioni sul metodo WdfUsbInterfaceSelectSetting e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.

Esempio

Nell'esempio di codice seguente viene inizializzata una struttura WDF_OBJECT_ATTRIBUTES con attributi per gli oggetti pipe creati dal framework. L'esempio inizializza quindi una struttura WDF_USB_INTERFACE_SELECT_SETTING_PARAMS per specificare l'impostazione alternativa 1. Infine, l'esempio chiama WdfUsbInterfaceSelectSetting per selezionare l'impostazione alternativa e creare oggetti pipe per le pipe dell'interfaccia.

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
                                      );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfusb.h (include Wdfusb.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)