WinUsb_ReadPipe 函数 (winusb.h)

  • 项目

WinUsb_ReadPipe 函数从指定管道读取数据。

语法

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
);

参数

[in] InterfaceHandle

接口的不透明句柄，其中包含与管道关联的终结点。

若要从与第一个接口中的终结点关联的管道读取数据，请使用 WinUsb_Initialize 返回的句柄。 对于所有其他接口，请使用目标接口的句柄， WinUsb_GetAssociatedInterface检索。

[in] PipeID

PipeID 对应于终结点描述符中的 bEndpointAddress 字段。 有关此字段布局的信息，请参阅 USB 技术“通用串行总线规范修订版 2.0”中的表 9-13。 在 bEndpointAddress 字段中，位 7 指示终结点的方向：0 表示 OUT;1 用于 IN。

[out] Buffer

调用方分配的缓冲区，用于接收读取的数据。

[in] BufferLength

最多读取的字节数。 此数字必须小于或等于 Buffer 的大小（以字节为单位）。

[out, optional] LengthTransferred

指向 ULONG 变量的指针，该变量接收复制到 缓冲区的实际字节数。 有关详细信息，请参阅“备注”。

[in, optional] Overlapped

指向用于异步操作的 OVERLAPPED 结构的可选指针。 如果指定此参数， WinUsb_ReadPipe 会立即返回，而不是同步等待操作完成，然后再返回。 操作完成时，会发出事件信号。

返回值

如果操作成功，WinUsb_ReadPipe返回 TRUE。 否则，此函数返回 FALSE，调用方可以通过调用 GetLastError 检索记录的错误。

GetLastError 可以返回以下错误代码。

返回代码 说明
ERROR_INVALID_HANDLE
 调用方在 InterfaceHandle 参数中传递 NULL。
ERROR_IO_PENDING
 重叠的 I/O 操作正在进行中，但尚未完成。 如果重叠的操作无法立即完成，则函数返回 FALSE，GetLastError 函数返回ERROR_IO_PENDING，表示操作正在后台执行。 调用 WinUsb_GetOverlappedResult 以检查操作的成功或失败。
ERROR_NOT_ENOUGH_MEMORY
 内存不足，无法执行操作。
ERROR_SEM_TIMEOUT
 由 USB 堆栈中的 WinUsb_ReadPipe 启动的读取操作在操作完成之前超时。

注解

如果设备返回的数据大于最大传输长度，WinUSB 会将请求划分为最大传输长度的较小请求，并按顺序提交它们。 如果传输长度不是终结点最大数据包大小的倍数， (可通过 WINUSB_PIPE_INFORMATION 结构的 MaximumPacketSize 成员) 检索，则 WinUSB 会将传输大小增加到下一个 MaximumPacketSize 倍数。

USB 数据包大小不考虑读取请求的传输。 如果设备响应的数据包对于客户端缓冲区来说太大，则读取请求的行为对应于管道上设置的策略类型。 如果管道的策略类型ALLOW_PARTIAL_READS，则 WinUSB 会将剩余数据添加到下一次传输的开头。 如果未设置ALLOW_PARTIAL_READS，读取请求将失败。 有关策略类型的详细信息，请参阅 用于管道策略修改的 WinUSB 函数。

如果应用程序将重叠参数 (同步操作) 传递 NULL，则应用程序必须确保 LengthTransferred 不是 NULL，即使读取操作不生成输出数据也是如此。

如果 重叠 不是 NULL (异步操作) ，则可以将 LengthTransferred 设置为 NULL。 对于重叠操作 (如果 LengthTransferred 是非 NULL 值) ，则在WinUsb_ReadPipe返回后在 LengthTransferred 中接收的值在重叠操作完成之前毫无意义。 若要检索从管道读取的实际字节数，请调用 WinUsb_GetOverlappedResult。

如果终结点中没有可用的数据， (管道为空) ， 则WinUsb_ReadPipe 在管道中存在数据之前不会返回。 如果出现错误情况或应用程序指定的超时过期， WinUsb_ReadPipe 始终返回 FALSE。 若要确定该返回值的实际原因，请始终调用 GetLastError。 例如，在这些情况下， GetLastError 错误值指示实际原因：

  • 如果应用程序在管道策略中指定了超时值，并且该超时过期， WinUsb_ReadPipe 返回 FALSE，GetLastError 将返回ERROR_SEM_TIMEOUT。
  • 如果在从管道读取数据时出现错误情况， WinUsb_ReadPipe 返回 FALSE，GetLastError 返回ERROR_GEN_FAILURE。

要求

要求 值
目标平台 通用
标头 winusb.h (包括 Winusb.h)
Library Winusb.lib
DLL Winusb.dll

另请参阅

WinUSB

WinUSB 函数

WinUsb_Initialize