Libusb开发教程二 API介绍与使用

背景介绍

上一篇博文主要介绍了 Libusb 在 Linux 系统下的详细安装过程，除了 libusb-1.0.9.tar.bz2 离线包之外，还安装了 libusb-compat-0.1.4.tar.bz2。顾名思义，第二个是先前版本的兼容包，因此在使用过程中，开发者就需要区分引用不同的 lib 版本了。libusb 较大版本变动以 V1.0 为分界线，访问官网：http://libusb.info 时也可以发现文档说明都以 V1.0 为主了。注意，libusb 已经从 libusb.org 切换到了 libusb.info。展示下最新网站首页：

分类十分明确，开发者可以直接从网站下载文档，API使用说明，例程等内容。V1.0 相对于之前版本，提供了更丰富的功能和接口，然而大部分情形下旧版本库提供的 API 函数功能已经可以满足我们应用的需要了，并且官网的源码安装包一直保持着对于老版本的兼容。出于兼容性以及大部分开发者使用习惯，本篇先基于老版本 Libusb 库 API 进行说明与使用介绍。

Libusb API 函数与功能

了解包含的 API 函数以及结构体相关定义等很简单，直接在安装路径下找到我们编程时需要引用的头文件即可，这里对应的头文件是 usb.h。我们打开 usb.h 可以看到，代码上部分为 usb 协议标准术语的宏定义，中间为相关结构体定义，后半部为我们编程引用的 API 声明，下面根据 API 功能和使用顺序进行分类描述：

核心初始化函数

1. void usb_init(void);

函数功能：libusb 初始化，这一步必须首先执行。

2. int usb_find_busses(void);

函数功能：查找系统上的 usb 总线，任何 usb 设备依附于 usb 总线和主机通信。成功返回 usb 总线数目，失败返回负值。

3. int usb_find_devices(void);

函数功能：查找总线上的 usb 设备，这个函数必须在调用 usb_find_busses() 后使用。成功返回设备数目，失败返回负值。

4. struct usb_bus *usb_get_busses(void);

函数功能：返回全局变量 usb_busses，用于遍历总线链表，查找总线 usb 设备。失败返回 NULL。这四步操作是任何程序必须首先执行的。

设备操作接口

1. usb_dev_handle *usb_open(struct usb_device *dev);

函数功能：打开 usb 设备，引用的 usb_dev_handle 以及 usb_device 结构体是 libusb 最常见的，定义可以参见头文件。函数返回 usb 设备的操作句柄，之后对该 usb 设备的操作都通过该句柄进行；

2. int usb_close(usb_dev_handle *dev);

函数功能：关闭 usb 设备，在所有操作完成后或者程序退出前调用，传入参数即上面提到的句柄，成功返回0；

3. int usb_get_string(usb_dev_handle *dev, int index, int langid, char *buf, size_t buflen);

函数功能：获取设备的字符串描述，通过 index 和 langid 进行索引。返回Unicode字符串到buf中，成功返回实际写入buf 的字节数，失败返回负值。

4. int usb_get_string_simple(usb_dev_handle *dev, int index, char *buf, size_t buflen);

函数功能：包装了 usb_get_string() 函数，返回第一种语言指定 index 索引的字符串描述，并转换到C风格的 ASCII。成功返回实际写入buf 的字节数，失败返回负值。

5. int usb_get_descriptor_by_endpoint(usb_dev_handle *udev, int ep, unsigned char type, unsigned char index, void *buf, int size);

函数功能：从设备获取描述符，以 type 和 index 索引，以ep标志的控制管道。成功返回实际写入buf 的字节数，失败返回负值。

6. int usb_get_descriptor(usb_dev_handle *udev, unsigned char type, unsigned char index, void *buf, int size);

函数功能：获取设备缺省控制管道的描述符，通过 type 和 index 索引。成功返回实际写入buf 的字节数，失败返回负值。

7. int usb_set_configuration(usb_dev_handle *dev, int configuration);

函数功能：设置当前设备使用的configuration，参数configuration 是设备配置描述符中的 bConfigurationValue。成功返回0，失败返回负值。

8. int usb_claim_interface(usb_dev_handle *dev, int interface);

函数功能：注册设备与操作系统通信的接口，interface 参数是接口描述符的 bInterfaceNumber 字段。这个函数必须被调用，因为只有注册接口，才能做相应的操作。必须在任何接口相关操作(如 usb_set_altinterface() 、 usb_bulk_write() 等)之前调用。成功返回0，失败返回负值。

9. int usb_release_interface(usb_dev_handle *dev, int interface);

函数功能：注销在 usb_claim_interface 中注册的通讯接口，释放相关资源，与注册函数成对使用。

10. int usb_set_altinterface(usb_dev_handle *dev, int alternate);

函数功能：设定当前接口中的活跃（起作用的）设置，alternate 为接口描述符中 bAlternateSetting 字段。成功返回0，失败返回负值。

11. int usb_resetep(usb_dev_handle *dev, unsigned int ep);

函数功能：复位指定的端点，参数 ep 为端点描述符中的 bEndpointAddress，此函数已被函数 usb_clear_halt 替代。成功返回0，失败返回负值。

12. int usb_clear_halt(usb_dev_handle *dev, unsigned int ep);

函数功能：复位指定的端点，参数 ep 为端点描述符中的 bEndpointAddress。成功返回0，失败返回负值。

13. int usb_reset(usb_dev_handle *dev);

函数功能：重置指定设备，通过发送 RESET 指令过去。返回0成功，负数失败。在执行该函数之后，需要重新枚举设备，且之前的句柄无法再工作。因此现在使用 usb_close 函数来替代。

14. int usb_get_driver_np(usb_dev_handle *dev, int interface, char *name, unsigned int namelen);

函数功能：获取设备接口对应的驱动程序名称，也即遍历 sysfs 系统中驱动与设备的对应关系，查找当前系统中有无该接口驱动，成功驱动名写入到 name 中且函数返回0，失败返回负值。

15. int usb_detach_kernel_driver_np(usb_dev_handle *dev, int interface);

函数功能：从内核中分离该接口驱动程序，也即禁止该驱动对设备起作用。这个步骤不可省略，不然会发现驱动和使用 Libusb 编写的应用程序同时对设备起作用，引起错误。使用时可以先通过 usb_get_driver_np 进行判断，如果有绑定的驱动程序，那么再调用此函数进行分离。成功返回0，失败返回负值。