libusb-win32介绍

1.介绍

这篇文档主要介绍libusb API工作的大致概况。适用于对usb2.0协议有一定了解的读者。如果对usb2.0不理解，可以从http://www.usb.org网站上下载usb2.0协议规格文档。libusb-0.1可以工作在linux、FreeBSD、NetBSD、OpenBSD、Darwin/Macos X、Solaris等操作系统下。libusb-win32的API不仅兼容libusb-0.1，而且好包含一些新的特性功能。

2.API

这些共应用程序调用使用的API相对比较精简，根据严格按照usb2.0的协议设计实现。

设备和接口

libusb API将打开的设备绑定到一个特定的接口。这就意味着如果你想在一个设备上请求更多的接口，就必须打开这个设备多次，这样通过调用usb_claim_interface()函数可以返回每个你想进行通信的接口的usb设备的句柄。

超时设定在libusb中通过被指定为毫秒级。

为了保持可移植性，libusb通常使用抽象和非抽象的结构体。

在最初版本的libusb0.1中，所有的功能函数都是同步实现的，这就意味着这些功能函数将会被阻塞来等待操作的完成或者在调用执行的应用程序返回之前timeout。libusb-win32增加了一些异步的API调用接口，libusb-1.0也开始支持异步API。

在libusb0.1中，函数有两种返回值，一种为usb_open函数返回打开的设备句柄handle，第二种为int型，当返回值大于等于0时表示成功，返回值小于0表示失败。

Timeout

timeout的基本最小单位为毫秒

在linux libusb-0.1中（仅支持同步API），timeout=0表示无限的。linusb-win32 1.2.4.7和以后最新的版本都支持这种API。像windows这种非实时操作系统，使用10ms或者100ms级timeout值并不是一个好方法。

当Timeout产生时的同步传输注意事项

同步API工作流程：

1.向底层驱动提交读请求

2.通过使用WaitForSingleobject()函数等待特定的timeout

   1.如果一个timeout产生时，发送中止管道请求并返回-116

   2.如果wait成功，通过GetOverlappedResults()函数获取传输结果并返回error或    传输的数据长度。

当刚刚检测到timeout传输完成，整个传输也是失败的。

有两种方法可以避免这种情况：

1.使用异步传输，比如使用usb_reap_async_nocancel()函数

2.在其自己的线程内使用异步传输并将timeout设置为INFINITE。

报告错误代码

在WDK crt_errno.h文件中标准的错误代码和一些MinGW的说明如下：

注意，并不是所有的错误代码都会被使用。

 #define EPERM       1   /* Operation not permitted */

 #define ENOENT      2   /* No entry, ENOFILE, no such file or directory */

 #define ESRCH       3   /* No such process */

 #define EINTR       4   /* Interrupted function call */

 #define EIO     5   /* Input/output error */

 #define ENXIO       6   /* No such device or address */

 #define E2BIG       7   /* Arg list too long */

 #define ENOEXEC     8   /* Exec format error */

 #define EBADF       9   /* Bad file descriptor */

 #define ECHILD      10  /* No child processes */

 #define EAGAIN      11  /* Resource temporarily unavailable */

 #define ENOMEM      12  /* Not enough space */

 #define EACCES      13  /* Permission denied */

 #define EFAULT      14  /* Bad address */

 #define EBUSY       16  /* strerror reports "Resource device" */

 #define EEXIST      17  /* File exists */

 #define EXDEV       18  /* Improper link (cross-device link?) */

 #define ENODEV      19  /* No such device */

 #define ENOTDIR     20  /* Not a directory */

 #define EISDIR      21  /* Is a directory */

 #define EINVAL      22  /* Invalid argument */

 #define ENFILE      23  /* Too many open files in system */

 #define EMFILE      24  /* Too many open files */

 #define ENOTTY      25  /* Inappropriate I/O control operation */

 #define EFBIG       27  /* File too large */

 #define ENOSPC      28  /* No space left on device */

 #define ESPIPE      29  /* Invalid seek (seek on a pipe?) */

 #define EROFS       30  /* Read-only file system */

 #define EMLINK      31  /* Too many links */

 #define EPIPE       32  /* Broken pipe */

 #define EDOM        33  /* Domain error (math functions) */

 #define ERANGE      34  /* Result too large (possibly too small) */

 #define EDEADLK     36      /* Resource deadlock avoided */

 #define ENAMETOOLONG    38  /* Filename too long */

 #define ENOLCK      39  /* No locks available */

 #define ENOSYS      40  /* Function not implemented */

 #define ENOTEMPTY   41  /* Directory not empty */

3.功能

3.1 内核

这些函数主要包括libusb的内核，这些函数会被使用libusb的应用程序调用。

usb_init() 

初始化libusb

正如其名，usb_init设置了一些内部结构体。usb_init必须在libusb的其他功能函数之前被调用。

usb_find_busses()

寻找系统中的usb总线

usb_find_busses()函数将会寻找在系统中的所有总线，返回总线的变化情况，先前调用该函数会返回新的总线和移除的总线的个数。

usb_find_devices()

扫描在usb总线上的所有设备

该函数会扫描在每条usb总线上的所有设备，该函数要在usb_find_busses()函数后调用。

usb_get_busses()

usb_set_debug()

该函数设置调试信息的信息级别，设置为4就可以得到信息的调试信息。

 0 LOG_OFF

 1 LOG_ERROR

 2 LOG_WARNING

 3 LOG_INFO

 4 LOG_DEBUG

3.2 设备操作

该组函数主要是与设备相关的操作，如打开、关闭设备等一些usb标准的操作：设置配置、 alternate settings、clearing halts和重启设备等。同时也会提供操作系统级的操作，如声明和释放接口。

usb_open()

打开一个usb设备，打开设备成功会返回一个句柄，以后的程序就可以通过该句柄来进行设备的通信。

usb_close()

关闭usb设备

返回0：关闭设备成功

小于0：关闭设备失败

usb_set_configuration()

根据配置描述符来设置一个使能的usb设备。

返回0：设置成功

小于0：设置失败

usb_set_altinterface()

设置当前接口的一个可选择的setting

usb_resetep()

reset端点

usb_clear_halt()

清除特定端点上的halt状态

usb_reset()

通过想下行端口发送一个RESET来重启连接该PORT的特定的设备

返回0：reset成功

小于0：reset失败

重新枚举

调用usb_reset设备重启后，设备会重新进行枚举成一个新设备并打开一个新句柄。

usb_claim_interface()

声明一个有操作系统相关的接口，接口的参数在描述符里的bInterfaceNumber字段里指定。

注意：在进行与该接口相关的操作之前，usb_claim_interface必须被首先调用。

返回值：

EBUSY ：接口是不可用的

ENOMEM：没有足够的内存可用

usb_release_interface()

释放先前usb_claim_interface声明的接口

3.3 控制传输

该组函数的主要功能是允许应用程序可以给默认的控制管道发送消息。

usb_control_msg()

给设备发送一个控制消息

usb_get_string()

重新从设备获取字符串描述符

usb_get_string_simple()

该函数是对usb_get_string()的封装，从设备重新获取设备描述符并将其转换成C语言格式的ASCII。

usb_get_descriptor()

通过设备默认的控制管道向设备重新获取设备描述符。

usb_get_descriptor_by_endpoint()

从端点识别的控制管道去获取设备描述符。

3.4.批量传输

该组函数允许应用程序通过批量传输管道向设备发送信息

usb_bulk_write()

向一个批量传输端点向设备写入数据

usb_bulk_read()

向一个批量传输端点向设备读取数据

3.5 中断传输

该组函数允许应用程序通过中断传输管道向设备发送和接受数据。

usb_interrupt_write()

向一个中断端点写数据。该函数会向指定的端点发起一个中断写请求。

usb_interrupt_read()

向一个中断端点写数据。该函数会向指定的端点发起一个中断读请求。

3.6异步API和异步传输

libusb-win32通过异步API支持异步传输。libusb-win32异步传输API也支持其他的传输类型：控制传输、中断传输、批量传输等。

int usb_isochronous_setup_async(usb_dev_handle *dev, void **context, unsigned char ep, int pktsize);

为端点ep分配一个异步传输请求。

 int usb_bulk_setup_async(usb_dev_handle *dev, void **context, unsigned char ep);

 int usb_bulk_setup_async(usb_dev_handle *dev, void **context, unsigned char ep);

 int usb_submit_async(void *context, char *bytes, int size);

 int usb_reap_async(void *context, int timeout);等待请求完成，返回读写成功的字节数或者失败的返回值。

 int usb_reap_async_nocancel(void *context, int timeout);

 int usb_cancel_async(void *context);取消

 int usb_free_async(void **context);

使用示例：

在使用设备之前，设备需要被扫描到，这可以通过扫描系统中的总线和usb总线上的设备来实现。

 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) {

          /* Check if this device is a printer */

          if (dev->descriptor.bDeviceClass == 7) {

              /* Open the device, claim the interface and do your processing */

              ...

          }

          for (c = 0; c < dev->descriptor.bNumConfigurations; c++) { /* Loop through all of the configurations */

              /* Loop through all of the interfaces */

              for (i = 0; i < dev->config[c].bNumInterfaces; i++) {

                  /* Loop through all of the alternate settings */

                  for (a = 0; a < dev->config[c].interface[i].num_altsetting; a++) {

                      /* Check if this interface is a printer */

                      if (dev->config[c].interface[i].altsetting[a].bInterfaceClass == 7) {

                      /* Open the device, set the alternate setting, claim the interface and do your processing */

                         ...

                      }

                  }

              }

          }

      }

  }