Función WdfUsbTargetDeviceSelectConfig (wdfusb.h)

Artículo
08/08/2023

[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 usa el autor de la llamada y el marco 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 valores siguientes:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_INFO_LENGTH_MISMATCH	El miembro Size de la estructura WDF_USB_DEVICE_SELECT_CONFIG_PARAMS a la que apunta Params era incorrecto.
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 contipode parámetros-> establecido en cualquiera de los siguientes elementos: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Para obtener más información, consulta WdfUsbTargetDeviceSelectConfigType.

Este método también podría devolver otros valores NTSTATUS.

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

Comentarios

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 marco 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 de trabajo 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 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	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)