Funzione WdfUsbTargetDeviceSelectConfig (wdfusb.h)

Articolo
02/07/2025

[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 gli 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 che il chiamante e il framework usano per specificare i parametri di configurazione.

Valore restituito

WdfUsbTargetDeviceSelectConfig restituisce il valore di stato di completamento della destinazione 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 di WDF_USB_DEVICE_SELECT_CONFIG_PARAMS che Params punta a 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 con Params->Type impostato su uno dei seguenti elementi: 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.

Osservazioni

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

Il framework crea un oggetto pipe USB del framework per ogni pipe associata a ogni interfaccia nella configurazione, dopo aver eliminato tutti gli 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 di WdfUsbTargetDeviceSelectConfig e sulle destinazioni di I/O USB, vedere Destinazioni 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.

Esempi

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

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	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)