Función WdfUsbTargetDeviceSelectConfig (wdfusb.h)

Artículo
02/07/2025

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceSelectConfig selecciona una configuración USB para un dispositivo o desconfigura el dispositivo.

Sintaxis

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

Parámetros

[in] UsbDevice

Identificador de un objeto de dispositivo USB obtenido de una llamada anterior a WdfUsbTargetDeviceCreateWithParameters.

[in, optional] PipeAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que contiene atributos para los nuevos objetos de canalización USB del marco que crea el marco para las interfaces del dispositivo. En el caso de los controladores KMDF, este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES. Los controladores UMDF deben establecer este parámetro en NULL.

[in, out] Params

Puntero a una estructura de WDF_USB_DEVICE_SELECT_CONFIG_PARAMS asignada por el autor de la llamada que el autor de la llamada y el marco usan para especificar parámetros de configuración.

Valor devuelto

WdfUsbTargetDeviceSelectConfig devuelve el valor de estado de finalización del destino de E/S si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se detectó un parámetro no válido.
STATUS_INFO_LENGTH_MISMATCH	El miembro Size de la estructura de WDF_USB_DEVICE_SELECT_CONFIG_PARAMS que Params apunta a no era correcto.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un búfer de memoria.
STATUS_NOT_SUPPORTED	El marco devuelve este valor si un controlador UMDF llama a WdfUsbTargetDeviceSelectConfig con Params->Type establecido en cualquiera de las siguientes opciones: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Para obtener más información, consulta WdfUsbTargetDeviceSelectConfigType.

Este método también puede devolver otros valores de NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Observaciones

El controlador puede seleccionar una configuración de dispositivo mediante una estructura de WDF_USB_DEVICE_SELECT_CONFIG_PARAMS para especificar descriptores USB, un URB o identificadores para crear marcos de objetos de interfaz USB.

El marco crea un objeto de canalización USB de marco para cada canalización asociada a cada interfaz de la configuración, después de eliminar los objetos de canalización que el marco podría haber creado previamente para la configuración. El marco usa la configuración alternativa cero para cada interfaz, a menos que el controlador especifique una configuración alternativa diferente.

Para obtener información sobre los objetos de canalización de una interfaz, el controlador puede llamar a WdfUsbInterfaceGetNumConfiguredPipes y WdfUsbInterfaceGetConfiguredPipe.

Para obtener más información sobre el método de WdfUsbTargetDeviceSelectConfig y los destinos de E/S USB, consulte destinos de E/S USB.

precaución

Puede usar WdfUsbTargetDeviceSelectConfig para seleccionar solo la primera configuración USB que aparece en la lista de descriptores, pero puede seleccionar varias interfaces dentro de esta única configuración.

Ejemplos

En el ejemplo de código siguiente se selecciona una configuración con una única interfaz especificada.

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

En el ejemplo de código siguiente se selecciona una configuración con varias interfaces, usando el valor alternativo cero en todas las interfaces. Este ejemplo solo se aplica a los controladores 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;
}

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
versión mínima de UMDF	2.0
encabezado de	wdfusb.h (incluya Wdfusb.h)
biblioteca de	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)