Función WdfUsbTargetDeviceRetrieveConfigDescriptor (wdfusb.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceRetrieveConfigDescriptor recupera el descriptor de configuración USB para el dispositivo USB asociado a un objeto de dispositivo USB de marco especificado.

Sintaxis

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

Parámetros

[in] UsbDevice

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

[out] ConfigDescriptor

Puntero a un búfer asignado por el autor de la llamada que recibe una estructura de USB_CONFIGURATION_DESCRIPTOR , seguida de una o varias estructuras de USB_INTERFACE_DESCRIPTOR y USB_ENDPOINT_DESCRIPTOR . Este parámetro es opcional y puede ser NULL, en cuyo caso WdfUsbTargetDeviceRetrieveConfigDescriptor devuelve la longitud del búfer necesaria. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, out] ConfigDescriptorLength

Puntero a una ubicación que proporciona la longitud del búfer al que apunta ConfigDescriptor . Si el puntero proporcionado para ConfigDescriptor es NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor devuelve la longitud de búfer necesaria en la ubicación a la que apunta ConfigDescriptorLength.

Valor devuelto

WdfUsbTargetDeviceRetrieveConfigDescriptor devuelve STATUS_SUCCESS 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_DEVICE_STATE	Un descriptor de configuración no estaba disponible para el destino especificado.
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_BUFFER_TOO_SMALL	El tamaño del búfer especificado era demasiado pequeño para los datos o el autor de la llamada proporcionó NULL para el parámetro ConfigDescriptor .

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 método WdfUsbTargetDeviceRetrieveConfigDescriptor recupera toda la información de configuración del dispositivo USB especificado (es decir, el descriptor de configuración más cualquier descriptor de interfaz o punto de conexión que pueda estar presente). Para obtener información sobre el formato de esta información, consulte la especificación USB.

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.

Los controladores deben llamar a WdfUsbTargetDeviceRetrieveConfigDescriptor dos veces, como se indica a continuación:

Establezca el puntero ConfigDescriptor en NULL, de modo que WdfUsbTargetDeviceRetrieveConfigDescriptor devuelva el tamaño de búfer necesario en la dirección a la que ConfigDescriptorLength apunta.
Asigne espacio de búfer para contener la información de configuración. Por ejemplo, un controlador podría llamar a ExAllocatePoolWithTag para asignar un búfer o podría llamar a WdfMemoryCreate para crear un objeto de memoria del marco.
Vuelva a llamar a WdfUsbTargetDeviceRetrieveConfigDescriptor , pasando un puntero al nuevo búfer y el tamaño del búfer.

Después de la segunda llamada a WdfUsbTargetDeviceRetrieveConfigDescriptor , el búfer al que apunta ConfigDescriptor contiene una estructura de USB_CONFIGURATION_DESCRIPTOR , seguida de una o varias estructuras de USB_INTERFACE_DESCRIPTOR y USB_ENDPOINT_DESCRIPTOR . Estas últimas estructuras se organizan en el orden descrito en la especificación USB.

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

Ejemplos

En el ejemplo de código siguiente se llama a WdfUsbTargetDeviceRetrieveConfigDescriptor para obtener el tamaño de búfer necesario, llama a WdfMemoryCreate para crear un objeto de memoria y búfer y, a continuación, llama a WdfUsbTargetDeviceRetrieveConfigDescriptor de nuevo para obtener la información de configuración de un dispositivo.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

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)