función WinUsb_ControlTransfer (winusb.h)

Artículo
08/27/2023

La función WinUsb_ControlTransfer transmite datos de control sobre un punto de conexión de control predeterminado.

Sintaxis

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parámetros

[in] InterfaceHandle

Identificador opaco de una interfaz en la configuración seleccionada.

Para especificar el destinatario de una solicitud de control como todo el dispositivo o la primera interfaz, use el identificador devuelto por WinUsb_Initialize. Para todas las demás interfaces, obtenga el identificador de la interfaz de destino llamando a WinUsb_GetAssociatedInterface y, a continuación, llame a WinUsb_ControlTransfer especificando el identificador de interfaz obtenido.

[in] SetupPacket

Paquete de configuración de 8 bytes de tipo WINUSB_SETUP_PACKET.

[out] Buffer

Búfer asignado por el autor de la llamada que contiene los datos que se van a transferir. La longitud de este búfer no debe superar los 4 KB.

[in] BufferLength

Número de bytes que se van a transferir, no incluido el paquete de instalación. Este número debe ser menor o igual que el tamaño, en bytes, del búfer.

[out, optional] LengthTransferred

Puntero a una variable ULONG que recibe el número real de bytes transferidos. Si la aplicación no espera que se transfieran datos durante la fase de datos (BufferLength es cero), LengthTransferred puede ser NULL.

[in, optional] Overlapped

Puntero opcional a una estructura SUPERPUESTA , que se usa para las operaciones asincrónicas. Si se especifica este parámetro, WinUsb_ControlTransfer devuelve inmediatamente y el evento se señala cuando se completa la operación. Si no se proporciona Superposición , la función WinUsb_ControlTransfer transfiere datos de forma sincrónica.

Valor devuelto

WinUsb_ControlTransfer devuelve TRUE si la operación se realiza correctamente. De lo contrario, esta rutina devuelve FALSE y el autor de la llamada puede recuperar el error registrado llamando a GetLastError.

GetLastError puede devolver uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_INVALID_HANDLE	El llamador pasó NULL en el parámetro InterfaceHandle .
ERROR_NOT_ENOUGH_MEMORY	Indica que no hay memoria suficiente para realizar la operación.

Comentarios

El host siempre envía una solicitud de control al punto de conexión predeterminado de un dispositivo USB, pero el destinatario de la solicitud puede ser todo el dispositivo, una interfaz o un punto de conexión en la configuración alternativa seleccionada. En la llamada WinUsb_ControlTransfer , la aplicación debe indicar al destinatario a través de dos parámetros: InterfaceHandle y SetupPacket.

Si el destinatario de una solicitud de control es todo el dispositivo, la primera interfaz o cualquier punto de conexión de esa interfaz, la aplicación debe usar el identificador devuelto por WinUsb_Initialize. Si el destinatario es cualquier otra interfaz o su punto de conexión, la aplicación debe obtener el identificador winUSB asociado a la interfaz de destino llamando a WinUsb_GetAssociatedInterface y, a continuación, llamar a WinUsb_ControlTransfer especificando el identificador de interfaz obtenido.

Según la sección 9.3 de la especificación USB oficial, el token de instalación de una transferencia de control contiene información sobre la solicitud. Para una aplicación WinUSB, ese token de instalación se describe mediante la estructura WINUSB_SETUP_PACKET .

Dentro del token de instalación, los campos bmRequestType y wIndex se usan para indicar el destinatario de la solicitud. Esos campos corresponden a los miembros RequestType e Index de WINUSB_SETUP_PACKET, respectivamente.

Los dos bits más bajos de RequestType indican el destinatario de la solicitud. El destinatario puede ser el dispositivo, una interfaz, un punto de conexión u otro (para la solicitud del proveedor). Dependiendo del destinatario, el byte inferior de Index indica el índice definido por el dispositivo del destinatario. El valor de Index depende del tipo de solicitud. Por ejemplo, para las solicitudes de control estándar, el valor es 0 o indica el número de interfaz o punto de conexión. Para determinados tipos de solicitudes estándar, como una solicitud de GET_DESCRIPTOR para obtener un descriptor de cadena, el valor index indica el identificador de idioma.

Si el destinatario es el dispositivo, la aplicación debe establecer los valores RequestType e Index . Los dos bits más bajos del valor RequestType deben ser 0. El byte inferior del valor index depende del tipo de solicitud. InterfaceHandle debe ser el identificador winUSB devuelto por WinUsb_Initialize.

Si el destinatario de la solicitud es una interfaz, la aplicación debe establecer los dos bits más bajos de RequestType en 0x01. La aplicación no es necesaria para establecer el byte inferior de Index para cualquier tipo de solicitud. Para las solicitudes estándar, de clase y de proveedor, Winusb.sys establece el valor en el número de interfaz de la interfaz de destino. InterfaceHandle debe estar asociado a la interfaz de destino. La aplicación puede obtener ese identificador llamando a WinUsb_GetAssociatedInterface.

Si el destinatario es un punto de conexión, la aplicación debe establecer los dos bits más bajos de RequestType en 0x02 e inferior byte de Index en la dirección del punto de conexión. En este caso, InterfaceHandle está asociado a la interfaz que contiene el punto de conexión. La aplicación puede obtener ese identificador llamando a WinUsb_GetAssociatedInterface.