función WinUsb_ReadPipe (winusb.h)

Artículo
08/27/2023

La función WinUsb_ReadPipe lee datos de la canalización especificada.

Sintaxis

BOOL WinUsb_ReadPipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [out]           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 leer datos de la 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.

[out] Buffer

Búfer asignado por el autor de la llamada que recibe los datos leídos.

[in] BufferLength

Número máximo de bytes que se pueden leer. 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 que se copiaron en buffer. 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_ReadPipe devuelve inmediatamente en lugar de esperar sincrónicamente a que se complete la operación antes de devolver. Se señala un evento cuando se completa la operación.

Valor devuelto

WinUsb_ReadPipe 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	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	No hay memoria suficiente para realizar la operación.
ERROR_SEM_TIMEOUT	La operación de lectura iniciada por WinUsb_ReadPipe en la pila USB agota el tiempo de espera antes de que se pudiera completar la operación.

Comentarios

Si los datos devueltos por el dispositivo son mayores que una longitud máxima de transferencia, WinUSB divide la solicitud en solicitudes más pequeñas de longitud máxima de transferencia y las envía en serie. Si la longitud de la transferencia no es un múltiplo del tamaño máximo de paquete del punto de conexión (recuperable a través del miembro MaximumPacketSize de la estructura WINUSB_PIPE_INFORMATION), WinUSB aumenta el tamaño de la transferencia al siguiente múltiplo de MaximumPacketSize.

El tamaño del paquete USB no tiene en cuenta la transferencia de una solicitud de lectura. Si el dispositivo responde con un paquete demasiado grande para el búfer de cliente, el comportamiento de la solicitud de lectura corresponde al tipo de directiva establecido en la canalización. Si el tipo de directiva de la canalización es ALLOW_PARTIAL_READS, WinUSB agrega los datos restantes al principio de la transferencia siguiente. Si no se establece ALLOW_PARTIAL_READS, se produce un error en la solicitud de lectura. Para obtener más información sobre los tipos de directiva, vea Funciones winUSB para la modificación de directivas de canalización.

Si una aplicación pasa NULL en el parámetro Superpuesto (operación sincrónica), la aplicación debe asegurarse de que LengthTransferred no es NULL, incluso cuando la operación de lectura 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_ReadPipe devuelve no tiene sentido hasta que se haya completado la operación superpuesta. Para recuperar el número real de bytes leídos de la canalización, llame a WinUsb_GetOverlappedResult.

Cuando no hay datos disponibles en el punto de conexión (la canalización está vacía), WinUsb_ReadPipe no devuelve hasta que haya datos en la canalización. Si se produce una condición de error o expira el tiempo de espera especificado por la aplicación, WinUsb_ReadPipe siempre devuelve FALSE. Para determinar el motivo real de ese valor devuelto, llame siempre a GetLastError. Por ejemplo, en estos casos, el valor de error GetLastError indica el motivo real:

Si la aplicación especificó un valor de tiempo de espera en la directiva de canalización y expira ese tiempo de espera, WinUsb_ReadPipe devuelve FALSE y GetLastError devuelve ERROR_SEM_TIMEOUT.
Si se produce una condición de error al leer datos de la canalización, WinUsb_ReadPipe devuelve FALSE y GetLastError devuelve ERROR_GEN_FAILURE.