WinUsb_WritePipe 函数 (winusb.h)

项目
03/13/2024

WinUsb_WritePipe函数将数据写入管道。

语法

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

参数

[in] InterfaceHandle

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

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

[in] PipeID

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

[in] Buffer

调用方分配的缓冲区，其中包含要写入的数据。

[in] BufferLength

要写入的字节数。此数字必须小于或等于 Buffer 的大小（以字节为单位）。

[out, optional] LengthTransferred

指向 ULONG 变量的指针，该变量接收写入管道的实际字节数。有关详细信息，请参阅“备注”。

[in, optional] Overlapped

指向 OVERLAPPED 结构的可选指针，用于异步操作。如果指定此参数， WinUsb_WritePipe 将立即返回，并在操作完成时向事件发出信号。

返回值

如果操作成功，WinUsb_WritePipe返回 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_WritePipe 启动的写入操作在操作完成之前超时。

注解

若要创建写入请求，应用程序必须分配缓冲区，用要写入设备的数据填充缓冲区，并通过调用 WinUsb_WritePipe 将缓冲区发送到主机控制器。

如果设置了RAW_IO，则以下限制适用于缓冲区的大小：

缓冲区长度必须是最大终结点数据包大小的倍数。
长度必须小于或等于 WinUsb_GetPipePolicy检索MAXIMUM_TRANSFER_SIZE的值。

如果未将RAW_IO设置为管道的策略类型，则缓冲区的大小没有限制。如果缓冲区的大小大于 MAXIMUM_TRANSFER_SIZE 报告的最大传输长度，WinUSB 会将请求划分为较小的请求，并将它们串行提交到主机控制器。

包含零长度数据的写入请求在 USB 堆栈中向下转发。

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

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