Funzione WdfUsbTargetDeviceSelectConfig (wdfusb.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetDeviceSelectConfig seleziona una configurazione USB per un dispositivo oppure deconfigura il dispositivo.

Sintassi

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

Parametri

[in] UsbDevice

Handle per un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.

[in, optional] PipeAttributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES allocata dal chiamante che contiene attributi per i nuovi oggetti pipe USB del framework creati dal framework per le interfacce del dispositivo. Per i driver KMDF, questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES. I driver UMDF devono impostare questo parametro su NULL.

[in, out] Params

Puntatore a una struttura WDF_USB_DEVICE_SELECT_CONFIG_PARAMS allocata dal chiamante e dal framework per specificare i parametri di configurazione.

Valore restituito

WdfUsbTargetDeviceSelectConfig 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_INFO_LENGTH_MISMATCH	Membro Size della struttura WDF_USB_DEVICE_SELECT_CONFIG_PARAMS a cui punta Params non è corretto.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un buffer di memoria.
STATUS_NOT_SUPPORTED	Il framework restituisce questo valore se un driver UMDF chiama WdfUsbTargetDeviceSelectConfig contipoParams-> impostato su uno dei seguenti: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Per altre info, vedi WdfUsbTargetDeviceSelectConfigType.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

Il driver può selezionare una configurazione del dispositivo usando una struttura di WDF_USB_DEVICE_SELECT_CONFIG_PARAMS per specificare descrittori USB, un handle o un handle per framework oggetti interfaccia USB.

Il framework crea un oggetto pipe USB del framework per ogni pipe associata a ogni interfaccia nella configurazione, dopo l'eliminazione di eventuali oggetti pipe che il framework potrebbe aver creato in precedenza per la configurazione. Il framework usa l'impostazione alternativa zero per ogni interfaccia, a meno che il driver non specifichi un'impostazione alternativa diversa.

Per ottenere informazioni sugli oggetti pipe di un'interfaccia, il driver può chiamare WdfUsbInterfaceGetNumConfiguredPipes e WdfUsbInterfaceGetConfiguredPipe.

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

Attenzione

È possibile usare WdfUsbTargetDeviceSelectConfig per selezionare solo la prima configurazione USB elencata nell'elenco dei descrittori, ma è possibile selezionare più interfacce all'interno di questa singola configurazione.

Esempio

Nell'esempio di codice seguente viene selezionata una configurazione con una singola interfaccia specificata.

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

Nell'esempio di codice seguente viene selezionata una configurazione con più interfacce, usando l'impostazione alternativa zero in tutte le interfacce. Questo esempio si applica solo ai driver 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;
}

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)