libusb开发者指南

libusb开发者指南

本文档描述libusb的API，以及如何开发USB应用。目录

• 1   介绍
  • 1.1   概览
  • 1.2   当前OS支持
• 2   API
  • 2.1   设备与接口
  • 2.2   超时
  • 2.3   数据类型
  • 2.4   同步
  • 2.5   返回值
• 3   函数
  • 3.1   核心函数
  • 3.2   设备操作
  • 3.3   控制传输
  • 3.4   块传输
  • 3.5   中断传输
  • 3.6   不可移植
• 4   例子
  • 4.1   简单例子
  • 4.2   源码包的例子
  • 4.3   其他应用

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() 等)之前调用。

返回码：

1. EBUSY ：接口无效，无法被认领
2. 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   其他应用

其他应用就参考其他的项目吧：

1. gPhoto ：使用libusb与相机通信
2. rio500 ：使用libusb与SONICblue Rio 500播放器