función WinUsb_WritePipe (winusb.h)

Artículo
08/27/2023

La función WinUsb_WritePipe escribe datos en una canalización.

Sintaxis

BOOL WinUsb_WritePipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [in]            PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parámetros

[in] InterfaceHandle

Identificador opaco de la interfaz que contiene el punto de conexión con el que está asociada la canalización.

Para escribir en una canalización asociada a un punto de conexión en la primera interfaz, use el identificador devuelto por WinUsb_Initialize. Para todas las demás interfaces, use el identificador de la interfaz de destino, recuperado por WinUsb_GetAssociatedInterface.

[in] PipeID

PipeID corresponde al campo bEndpointAddress en el descriptor del punto de conexión. Para obtener información sobre el diseño de este campo, vea la tabla 9-13 en "Universal Serial Bus Specification Revision 2.0" at USB Technology. En el campo bEndpointAddress , Bit 7 indica la dirección del extremo: 0 para OUT; 1 para IN.

[in] Buffer

Búfer asignado por el autor de la llamada que contiene los datos que se van a escribir.

[in] BufferLength

Número de bytes que se van a escribir. 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 escritos en la canalización. Para obtener más información, vea la sección Comentarios.

[in, optional] Overlapped

Puntero opcional a una estructura SUPERPUESTA, que se usa para las operaciones asincrónicas. Si se especifica este parámetro, WinUsb_WritePipe devuelve inmediatamente y el evento se señala cuando se completa la operación.

Valor devuelto

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

GetLastError puede devolver el siguiente código de error.

Código devuelto	Descripción
ERROR_INVALID_HANDLE	El llamador pasó NULL en el parámetro InterfaceHandle .
ERROR_IO_PENDING	Indica que una operación de E/S superpuesta está en curso, pero no se ha completado. Si la operación superpuesta no se puede completar inmediatamente, la función devuelve FALSE y la función GetLastError devuelve ERROR_IO_PENDING, lo que indica que la operación se está ejecutando en segundo plano. Llame a WinUsb_GetOverlappedResult para comprobar si la operación se ha realizado correctamente o no.
ERROR_NOT_ENOUGH_MEMORY	Indica que no hay memoria suficiente para realizar la operación.
ERROR_SEM_TIMEOUT	La operación de escritura iniciada por WinUsb_WritePipe en la pila USB agota el tiempo de espera antes de que se pudiera completar la operación.

Comentarios

Para crear una solicitud de escritura, la aplicación debe asignar un búfer, rellenarla con los datos que desea escribir en el dispositivo y enviar el búfer al controlador de host llamando a WinUsb_WritePipe.

Las restricciones siguientes se aplican al tamaño del búfer si se establece RAW_IO:

La longitud del búfer debe ser un múltiplo del tamaño máximo del paquete del punto de conexión.
La longitud debe ser menor o igual que el valor de MAXIMUM_TRANSFER_SIZE recuperada por WinUsb_GetPipePolicy.

No hay restricciones en el tamaño del búfer si RAW_IO no se establece como el tipo de directiva de la canalización. Si el tamaño del búfer es mayor que la longitud máxima de transferencia notificada por MAXIMUM_TRANSFER_SIZE, WinUSB divide la solicitud en solicitudes más pequeñas y las envía serialmente al controlador host.

Una solicitud de escritura que contiene datos de longitud cero se reenvía a la pila USB.

Si una aplicación pasa NULL en el parámetro Superpuesto (operación sincrónica), debe asegurarse de que LengthTransferred no sea NULL, incluso cuando una operación no genera datos de salida.

Si Superpuesto no es NULL (operación asincrónica), LengthTransferred se puede establecer en NULL. Para una operación superpuesta (y si LengthTransferred es un valor distinto de NULL ), el valor recibido en LengthTransferred después de WinUsb_WritePipe devuelve no tiene sentido hasta que se haya completado la operación superpuesta. Para recuperar el número real de bytes devueltos, llame a WinUsb_GetOverlappedResult.