libusb开发者入门指南

墨蓝 2022-09-26 03:06 201阅读 0赞

[http://www.cnblogs.com/ele-eye/p/3261970.html][http_www.cnblogs.com_ele-eye_p_3261970.html]

本文档描述libusb的API，以及如何开发USB应用。  
1 介绍  
1.1 概览  
本文档描述libusb-0.1的API和USB相关内容。  
1.2 当前OS支持  
Linux 2.2或以上  
FreeBSD/NetBSD/OpenBSD  
Darwin/MacOSX  
2 API  
2.1 设备与接口  
一个设备可能有多个接口，所以一个句柄可以返回多个接口实例。不要忘记调用 usb\_claim\_interface() 。  
2.2 超时  
总是以毫秒为单位。  
2.3 数据类型  
同时使用有抽象结构和非抽象结构来保持可移植性。  
2.4 同步  
所有libusb v0.1的函数都是同步的，这意味着操作完成或超时前不会返回。异步操作从libusb v1.0开始支持。  
2.5 返回值  
libusb v0.1有两种返回值。一种是 usb\_open() 返回的句柄，另一种是整数int，返回负数表示错误。  
3 函数  
3.1 核心函数  
void usb\_init(void);  
初始化libusb。  
int usb\_find\_busses(void);  
查找所有总线，返回上次调用以后改变的数量(包括新增的和移除的总线)。  
int usb\_find\_devices(void);  
寻找每个总线上的所有设备。应该在 usb\_find\_busses() 之后调用。返回上次调用后改变的数量(包括新增和移除的设备)。  
struct usb\_bus \*usb\_get\_busses(void);  
简单的返回全局变量 usb\_busses 。这仅对支持C调用规范和可以使用共享库的语言，但是不支持C全局变量的(例如Delphi)。  
3.2 设备操作  
这组函数用于操作设备。允许你打开关闭设备，设置配置、轮换设置、干净的关闭和重置设备。它也提供OS级别的操作，如认领(claim)和释放接 口。  
usb\_dev\_handle \*usb\_open(struct \*usb\_device dev);  
打开设备以供使用，返回设备句柄。  
int usb\_close(usb\_dev\_handle \*dev);  
关闭设备，返回0成功，负数失败。  
int usb\_set\_configuration(usb\_dev\_handle \*dev, int configuration);  
设置活跃配置。configuration参数是描述符bConfigurationValue字段的值。返回0成功，负数失败。  
int usb\_set\_altinterface(usb\_dev\_handle \*dev, int alternate);  
设置当前接口的活跃轮换设置。alternate参数是描述符bAlternateSetting字段的值。返回0成功，负数失败。  
int usb\_resetep(usb\_dev\_handle \*dev, unsigned int ep);  
重置指定端点的所有状态。ep参数是描述符的bEndpointAddress字段的值。返回0称公，负数失败。  
该接口不建议使用，你可能需要的是 usb\_clear\_halt() 。  
int usb\_clear\_halt(usb\_dev\_handle \*dev, unsigned int ep);  
清理端点所有停止状态，ep是描述符bEndpointAddress字段的值。返回0成功，负数失败。  
int usb\_reset(usb\_dev\_handle \*dev);  
重置指定设备，通过发送RESET指令过去。返回0成功，负数失败。  
在执行该函数之后，需要重新列举，找到设备。当前的句柄无法再工作了。  
int usb\_claim\_interface(usb\_dev\_handle \*dev, int interface);  
通过OS认领一个接口。interface参数是描述符的bInterfaceNumber字段。返回0成功，负数失败。  
必须在任何接口相关操作(如 usb\_set\_altinterface() 、 usb\_bulk\_write() 等)之前调用。  
返回码：  
EBUSY ：接口无效，无法被认领  
ENOMEM ：内存不足  
int usb\_release\_interface(usb\_dev\_handle \*dev, int interface);  
释放之前认领的接口。interface参数是描述符的bInterfaceNumber字段。返回0成功，负数失败。  
3.3 控制传输  
发送消息到缺省控制管道。  
int usb\_control\_msg(usb\_dev\_handle \*dev, int requesttype, int request, int value, int index, char \*bytes, int size, int timeout);  
发送控制请求到设备的缺省控制管道。参数对应USB规范中的同名类型。返回读写字节数，负数失败。  
int usb\_get\_string(usb\_dev\_handle \*dev, int index, int langid, char \*buf, size\_t buflen);  
获取设备的字符串描述，通过index和langdi索引。返回Unicode字符串到buf中。返回实际写入buf的字节数，负数失败。  
int usb\_get\_string\_simple(usb\_dev\_handle \*dev, int index, char \*buf, size\_t buflen);  
包装了 usb\_get\_string() 函数，返回第一种语言指定index索引的字符串描述，并转换到C风格的ASCII。返回写入buf字节数，负数失败。  
int usb\_get\_descriptor(usb\_dev\_handle \*dev, unsigned char type, unsigned char index, void \*buf, int size);  
获取设备缺省控制管道的描述符，通过type和index索引。返回实际写入buf的字节数，负数失败。  
参考 usb\_get\_descriptor\_by\_endpoint() 了解允许指定控制端点的。  
int usb\_get\_descriptor\_by\_endpoint(usb\_dev\_handle \*dev, int ep, unsigned char type, unsigned char index, void \*buf, int size);  
从设备获取描述符，以type和index索引，以ep标志的控制管道。返回读取字节数，负数失败。  
3.4 块传输  
这部分允许应用从数据块管道发送和接收数据。  
int usb\_bulk\_write(usb\_dev\_handle \*dev, int ep, char \*bytes, int size, int timeout);  
写入一块数据到端点ep，返回写入成功字节数，负数失败。  
int usb\_bulk\_read(usb\_dev\_handle \*dev, int ep, char \*bytes, int size, int timeout);  
读取一块数据，从端点ep，返回读取成功字节数，负数失败。  
3.5 中断传输  
这组函数允许应用发送和接收数据通过中断管道。  
int usb\_interrupt\_write(usb\_dev\_handle \*dev, int ep, char \*bytes, int size, int timeout);  
执行对端点ep的中断写入，返回实际写入字节数，负数失败。  
int usb\_interrupt\_read(usb\_dev\_handle \*dev, int ep, char \*bytes, int size, int timeout);  
执行对中断端点ep的读取，返回实际读取字节数，负数失败。  
3.6 不可移植  
这些函数是不可移植的。有些是暴露了OS USB API之类的。他们都回加上函数名后缀 \_np 。  
一个C预处理器宏会定义实现的函数。形式是 LIBUSB\_HAS\_ 加上函数名，没有 usb\_ 前缀。例如， usb\_get\_driver\_np() 实现了，就会定义 LIBUSB\_HAS\_GET\_DRIVER\_NP 。  
int usb\_get\_driver\_np(usb\_dev\_handle \*dev, int interface, char \*name, int namelen);  
这个函数获取接口驱动的名字。成功返回0，失败负数。  
只在Linux有实现。  
int usb\_detach\_kernel\_driver\_np(usb\_dev\_handle \*dev, int interface);  
这个函数从接口剥离内核驱动。使用了libusb的应用可以随即重新认领接口。返回0成功，负数失败。  
只在Linux有实现。  
4 例子  
4.1 简单例子  
与设备通信前要先找到它。需要先找到所有总线(busses)，然后找到所有设备:  
struct usb\_bus \*busses;  
usb\_init();  
usb\_find\_busses();  
usb\_find\_devices();  
busses=usb\_get\_busses();  
在这之后，应用应该手动轮询所有总线和设备，匹配其所要的:  
struct usb\_bus \*bus;  
int c,i,a;  
for (bus=busses; bus; bus=bus->next) \{  
struct usb\_device \*dev;  
for (dev=bus->devices; dev; dev=dev->next) \{  
if (dev->descriptor.bDeviceClass==7) \{  
/\*打开设备，认领接口，然后操作\*/  
\}  
/\*循环遍历所有配置\*/  
for (c=0; c< dev->descriptor.bNumConfigurations; c++) \{  
/\*循环遍历所有接口\*/  
for (i=0; i< dev->config\[c\].bNumInterfaces; i++) \{  
/\*循环遍历所有轮换设置\*/  
for (a=0; a< dev->config\[c\].interface\[i\].num\_altsetting; a++) \{  
/\*检查接口是否是打印机\*/  
if (dev->config\[c\].interface\[i\].altsetting\[a\].bInterfaceClass==7) \{  
/\*打开设备，设置轮换配置，认领接口，然后操作\*/  
\}  
\}  
\}  
\}  
\}  
\}  
4.2 源码包的例子  
tests目录有个程序叫 testlibusb.c 。它简单的调用libusb寻找所有设备，然后遍历并打印描述符。其结果很简单，不过用处有限。倒是可以作为很好的入门。  
4.3 其他应用  
其他应用就参考其他的项目吧：  
gPhoto ：使用libusb与相机通信  
rio500 ：使用libusb与SONICblue Rio 500播放器

[http_www.cnblogs.com_ele-eye_p_3261970.html]: http://www.cnblogs.com/ele-eye/p/3261970.html