WinUsb_ControlTransfer 函数 (winusb.h)

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 调用中,应用程序必须通过两个参数指示收件人: InterfaceHandleSetupPacket

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

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

在设置令牌中, bmRequestTypewIndex 字段用于指示请求的收件人。 这些字段分别对应于WINUSB_SETUP_PACKETRequestTypeIndex 成员。

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

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

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

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

要求

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

另请参阅

WINUSB_SETUP_PACKET

WinUSB

WinUSB 函数

WinUsb_Initialize