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 可以返回以下错误代码之一。
返回代码 | 说明 |
---|---|
|
调用方在 InterfaceHandle 参数中传递 NULL。 |
|
指示内存不足,无法执行操作。 |
注解
控制请求始终由主机发送到 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 来获取该句柄。
要求
要求 | 值 |
---|---|
目标平台 | 通用 |
标头 | winusb.h (包括 Winusb.h) |
Library | Winusb.lib |
DLL | Winusb.dll |