WinUsb_ControlTransfer 函数 (winusb.h)

项目
08/27/2023

WinUsb_ControlTransfer 函数通过默认控制终结点传输控制数据。

语法

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

参数

[in] InterfaceHandle

所选配置中接口的不透明句柄。

若要将控制请求的接收方指定为整个设备或第一个接口，请使用 WinUsb_Initialize返回的句柄。对于所有其他接口，通过调用 WinUsb_GetAssociatedInterface 获取目标接口的句柄，然后通过指定获取的接口句柄来调用 WinUsb_ControlTransfer 。

[in] SetupPacket

WINUSB_SETUP_PACKET 类型的 8 字节安装数据包。

[out] Buffer

调用方分配的缓冲区，其中包含要传输的数据。此缓冲区的长度不能超过 4KB。

[in] BufferLength

要传输的字节数，不包括设置数据包。此数字必须小于或等于 Buffer 的大小（以字节为单位）。

[out, optional] LengthTransferred

指向接收实际传输字节数的 ULONG 变量的指针。如果应用程序不希望在数据阶段传输任何数据， (BufferLength 为零) ， 则 LengthTransferred 可以为 NULL。

[in, optional] Overlapped

指向用于异步操作的 OVERLAPPED 结构的可选指针。如果指定此参数， WinUsb_ControlTransfer 立即返回，并在操作完成时发出事件信号。如果未提供 Overlapped ， 则 WinUsb_ControlTransfer 函数会同步传输数据。

返回值

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

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

返回代码	说明
ERROR_INVALID_HANDLE	调用方在 InterfaceHandle 参数中传递 NULL。
ERROR_NOT_ENOUGH_MEMORY	指示内存不足，无法执行操作。

注解

控制请求始终由主机发送到 USB 设备的默认终结点，但请求的接收者可以是整个设备、接口或所选备用设置中的终结点。在 WinUsb_ControlTransfer 调用中，应用程序必须通过两个参数指示收件人： InterfaceHandle 和 SetupPacket。

如果控制请求的接收方是整个设备、第一个接口或该接口中的任何终结点，则应用程序必须使用 WinUsb_Initialize返回的句柄。如果接收方是任何其他接口或其终结点，则应用程序必须通过调用 WinUsb_GetAssociatedInterface 获取与目标接口关联的 WinUSB 句柄，然后通过指定获取的接口句柄来调用 WinUsb_ControlTransfer 。

根据官方 USB 规范的第 9.3 节，控制传输的设置令牌包含有关请求的信息。对于 WinUSB 应用程序，使用 WINUSB_SETUP_PACKET 结构描述该设置令牌。

在设置令牌中， bmRequestType 和 wIndex 字段用于指示请求的收件人。这些字段分别对应于WINUSB_SETUP_PACKET的 RequestType 和 Index 成员。

RequestType 的最低两位表示请求的接收方。接收者可以是供应商请求) 的设备、接口、终结点或其他 (。 Index 的较低 字节表示收件人的设备定义的索引，具体取决于收件人。 Index 的值取决于请求的类型。例如，对于标准控制请求，该值为 0，或指示接口或终结点编号。对于某些类型的标准请求（例如获取字符串描述符的GET_DESCRIPTOR请求）， Index 值指示语言 ID。

如果收件人是设备，则应用程序必须设置 RequestType 和 Index 值。 RequestType 值的最低两位必须为 0。 Index 值的较低字节取决于请求的类型。 InterfaceHandle 必须是WinUsb_Initialize返回的 WinUSB 句柄。

如果请求的接收方是接口，则应用程序必须将 RequestType 的最低两位设置为0x01。应用程序不需要为任何类型的请求设置索引的较低字节。对于标准、类和供应商请求，Winusb.sys 将值设置为目标接口的接口编号。 InterfaceHandle 必须与目标接口相关联。应用程序可以通过调用 WinUsb_GetAssociatedInterface 来获取该句柄。

如果接收方是终结点，则应用程序必须将 RequestType 的最低两位设置为 0x02，并将 Index 的较低字节设置为终结点地址。在这种情况下， InterfaceHandle 与包含终结点的接口相关联。应用程序可以通过调用 WinUsb_GetAssociatedInterface 来获取该句柄。