libusb Developers Guide
libusb 开发者指南

原作者：Johannes Erdfelt
翻译者：牛胜超

Table of Contents
目录

Preface
序言

I. Introduction         
   引言
   1. Overview
      概述
   2. Current OS support
      流行的操作系统支持

II. API                     
    应用程序接口
   3. Devices and interfaces
      设备和接口
   4. Timeouts              
      超时
   5. Data Types            
      数据类型
   6. Synchronous           
      同步的
   7. Return values         
      返回值

III. Functions              libusb 外部接口函数
     I. Core                libusb 外部接口函数之 核心　　　　　接口函数
    II. Device operations   libusb 外部接口函数之 设备操作　　　接口函数
   III. Control Transfers   libusb 外部接口函数之 控制端点传输　接口函数
    IV. Bulk Transfers      libusb 外部接口函数之 批量端点传输　接口函数
     V. Interrupt Transfers libusb 外部接口函数之 中断端点传输　接口函数
    VI. Non Portable        libusb 外部接口函数之 不可移植　　　接口函数

IV. Examples                               例子
    8. Basic Examples                      基本例子
    9. Examples in the source distribution 源码分布包中的例子
   10. Other Applications                  其它应用程序的例子

List of Tables     列表
   1. Return Codes 返回码

Preface
序言

This document's purpose is to explain the API for libusb
and how to use them to make a USB aware application.
本文档的目的是说明 libusb 的应用程序接口，且如何使用它们来制作一个有 USB 意识的应用程序。

Any suggestions,
corrections and comments regarding this document can be sent to the author:
Johannes Erdfelt or the libusb developers mailing list.
任何关于本文档的建议，纠正和意见可以发送给作者：Johannes Erdfelt 或 libusb 开发者邮件联系表。

I. Introduction
   引言

Table of Contents
目录

1. Overview           概述
2. Current OS support 流行的操作系统支持

Chapter 1. Overview
第一章：概述

This documentation will give an overview of
how the v0.1 libusb API works and relates to USB.
本文档将给出一个 libusb v0.1 应用程序接口工作如何涉及 USB 。

Work is rapidly progressing on a newer version of libusb, to be v1.0,
which will be a redesigned API and is intended to obsolete v0.1.
更新版的 libusb 的工作迅速，libusb v1.0 重新设计的应用程序接口将替代过时的 libusb v0.1 。

You may want to check the libusb website to see if it is stable and recommended.
你可能需要核对 libusb (http://libusb.sourceforge.net/)网站来看看它是不是稳定和被推荐的。

This documentation assumes that
you have a good understanding of USB and how it works.
本文档假定你已很好的理解了 USB 和它如何工作。

If you don't have a good understanding of USB,
it is recommended you obtain the USB v2.0 specs and read them.
如果你没有很好的理解 USB 的话，推荐你下载 USB v2.0 规范来读读。
(http://www.usb.org/developers/docs/usb_20_05122006.zip)
注：
1.目前无驱的技术主要分为：HID、SCSI、CCID 三种。
2.Endpoint：USB 通信最基本的形式是通过 USB 设备里一个叫做 Endpoint(端点) 的东西。
          　它是通信的发送或接收点。
          　它有确定的单一方向，要么为 in (设备 -> 主机)，要么为 out (主机 -> 设备)。
          　也有一个例外，USB 协议规定每个设备都必须有 Endpoint0，它是双向的，
          　USB 利用它来实现缺少的控制管道(Control Pipe)，从而控制设备。
3.Endpoint 有四种类型：
1)控制端点(Control Endpoint)：
  通常用于 配置设备、获取设备信息、发送命令到设备、获取设备的状态报告等，即传输控制信息。
2)中断端点(Interrupt Endpoint)：
  当 USB 主机要求设备传输数据时，中断端点就以一个固定的速率来传送少量的数据。(USB键鼠即是此方式)
3)批量端点(Bulk Endpoint)：
  传输大批量数据，确保不丢失数据，但不保证特定时间内完成。(打印机、网络设备多用此方式)
4)同步端点(Isochronous Endpoint)：
  传输大批量数据，不保证数据是否到达，对传送延迟非常敏感，可保持一个恒定速率收发实时信息。(音视频设备多用此方式)

libusb is geared towards USB 1.1,
however from the perspective of libusb,
USB 2.0 won't be a significant change for libusb.
libusb 是基于 USB 1.1 ，无论如何从 libusb 的角度看，USB 2.0 没有重大变化。

Chapter 2. Current OS support
第二章：流行的操作系统支持

•Linux (2.2, 2.4 and on 和更高版本)
•FreeBSD, NetBSD and OpenBSD
•Darwin/MacOS X

II. API
    应用程序接口

This is the external API for applications to use.
提供给应用程序来使用的外部应用程序接口。

The API is relatively lean and designed to
have close analogies to the USB specification.
外部应用程序接口相对较少且设计上紧靠 USB 规范。

The v0.1 API was mostly hacked together and
kludged together without much forethought and as a result,
it's missing quite a few features.
libusb v0.1 外部应用程序接口是没有过多的考虑几乎是拼装攒凑而成，缺少一点功能。

v1.0 is intended to rectify this.
libusb v1.0 纠正替换它。

Table of Contents
目录

3. Devices and interfaces 设备和接口
4. Timeouts               超时
5. Data Types             数据类型
6. Synchronous            同步的
7. Return values          返回值

Chapter 3. Devices and interfaces
第三章：设备和接口

The libusb API ties an open device to a specific interface.
libusb v0.1 外部应用程序接口连接一个打开的设备到一个特定的接口。

This means that if you want to claim multiple interfaces on a device,
you should open the device multiple times to receive one usb_dev_handle
for each interface you want to communicate with.
这意味着如果你想要在一个设备上索取多种接口，你将打开该设备多次，
接收你想要联接的每一个接口的 usb_dev_handle 。

Don't forget to call usb_claim_interface.
不要忘了调用索取接口函数 usb_claim_interface 。
注：不要忘了调用释放接口函数 usb_release_interface 释放 usb_claim_interface 索取的接口。

Chapter 4. Timeouts
第四章：超时

Timeout's in libusb are always specified in milliseconds.
libusb 中超时一直指定用毫秒。

Chapter 5. Data Types
第五章：数据类型

libusb uses both abstracted and non abstracted structures to maintain portability.
libusb 使用 抽象 和 非抽象 结构来保持可移植性。

Chapter 6. Synchronous
第六章：同步的

All functions in libusb v0.1 are synchronous,
meaning the functions block and wait for the operation to finish or
timeout before returning execution to the calling application.
在 libusb v0.1 中全部函数是同步的，意味着在返回完成到调用应用程序之前，函数阻塞等待操作完成或超时。

Asynchronous operation will be supported in v1.0, but not v0.1.
异步的操作将是在 libusb v1.0 中被支持，而不是 libusb v0.1 。

Chapter 7. Return values
第七章：返回值

There are two types of return values used in libusb v0.1.
在 libusb v0.1 中有两种类型返回值。

The first is a handle returned by usb_open.
第一个是 usb_open 返回的一个句柄(usb_dev_handle)。

The second is an int.
第二个是一个整型。

In all cases where an int is returned,
>= 0 is a success and < 0 is an error condition.
返回整型值在全部情况中，大于等于零(>=0)为成功，小于零(<0)是出错状态。

III. Functions libusb 外部接口函数

I. Core
   libusb 外部接口函数之 核心 接口函数

These functions comprise the core of libusb.
这些函数构成了 libusb 的核心。

They are used by all applications that utilize libusb.
它们是被全部应用程序用来利用 libusb 。

Name
名字

usb_init -- Initialize libusb
            初始化 libusb

Description
描述

void
usb_init( void );

Just like the name implies,
usb_init sets up some internal structures.
正像名字暗示的那样，usb_init 设置一些内部结构体。

usb_init must be called before any other libusb functions.
usb_init 必须在调用其它 libusb 函数之前被调用。

Name
名字

usb_find_busses -- Finds all USB busses on system　
                   在系统上查找全部 usb 总线

Description
描述

int
usb_find_busses( void );

usb_find_busses will find all of the busses on the system.
usb_find_busses 将在系统上查找全部 usb 总线。
注：任何 usb 设备都通过 usb 总线和计算机总线通信。

Returns the number of changes since previous call to this function
(total of new busses and busses removed).
返回自从上次调用以后改变的 usb 总线总数量(包括新增加的和移除的 usb 总线的总数量)。

Name
名字

usb_find_devices -- Find all devices on all USB busses
                    在全部 usb 总线上查找全部设备

Description
描述

int
usb_find_devices( void );

usb_find_devices will find all of the devices on each bus.
usb_find_devices 将查找每个 usb 总线上的全部设备。

This should be called after usb_find_busses.
这将是在 usb_find_busses 调用之后被调用。

Returns the number of changes since the previous call to this function
(total of new device and devices removed).
返回自从上次调用以后改变的设备总数(包括新增加的和移除的设备的总数量)。

Name
名字

usb_get_busses -- Return the list of USB busses found
                  返回查找到的 usb 总线列表

Description
描述

struct usb_bus*
usb_get_busses( void );

usb_get_busses simply returns the value of the global variable usb_busses.
usb_get_busses 简单地返回全局变量 usb_bus* usb_busses 的值。

This was implemented for those languages that
support C calling convention and can use shared libraries,
but don't support C global variables (like Delphi).
这是为支持 C 调用习惯且可以使用共享库，但是不支持 C 全局变量(像 Delphi)的语言实现的。

struct usb_bus {
  struct usb_bus *next, *prev;

  char dirname[PATH_MAX + 1];

  struct usb_device *devices;
  u_int32_t location;
};

struct usb_device {
  struct usb_device *next, *prev;

  char filename[PATH_MAX + 1];

  struct usb_bus *bus;

  struct usb_device_descriptor descriptor;
  struct usb_config_descriptor *config;

  void *dev;        // Darwin support 苹果公司的一个开源操作系统 达尔文 支持 */
};

// Device descriptor */
struct usb_device_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int16_t bcdUSB;
    u_int8_t  bDeviceClass;
    u_int8_t  bDeviceSubClass;
    u_int8_t  bDeviceProtocol;
    u_int8_t  bMaxPacketSize0;
    u_int16_t idVendor;
    u_int16_t idProduct;
    u_int16_t bcdDevice;
    u_int8_t  iManufacturer;
    u_int8_t  iProduct;
    u_int8_t  iSerialNumber;
    u_int8_t  bNumConfigurations;
};

II. Device operations
    libusb 外部接口函数之 设备操作 接口函数

This group of functions deal with the device.
这组函数处理涉及设备。

It allows you to open and close the device as well standard USB operations
like setting the configuration, alternate settings, clearing halts
and resetting the device.
这组函数允许你打开和关闭设备以及标准 USB 操作，像：设置配置，替代设置，清除停止状态和重置设备。

It also provides OS level operations such as claiming and releasing interfaces.
这组函数同样提供了操作系统级操作，例如：索取和释放接口。

Name
名字

usb_open -- Opens a USB device
            打开一个 usb 设备
Description
描述

usb_dev_handle*
usb_open( struct *usb_device dev );

usb_open is to be used to open up a device for use.
usb_open 是用来打开一个设备以供使用。

usb_open must be called before attempting to perform any operations to the device.
usb_open 必须在企图对设备执行任何操作前被调用。

Returns a handle used in future communication with the device.
返回一个句柄用于将来与设备通信。

struct usb_dev_handle {
  int fd;

  struct usb_bus *bus;
  struct usb_device *device;

  int config;
  int interface;
  int altsetting;

  // Added by RMT so implementations can store other per-open-device data */
  void *impl_info;
};


Name
名字

usb_close -- Closes a USB device
             关闭一个 usb 设备

Description
描述

int
usb_close( usb_dev_handle *dev );

usb_close closes a device opened with usb_open.
usb_close 关闭一个用 usb_open 函数打开的设备。

No further operations may be performed on the handle after usb_close is called.
调用过 usb_close 之后无更多的操作可以是在参数 dev 指向的句柄上执行。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

Name
名字

usb_set_configuration -- Sets the active configuration of a device
                         设置一个设备的有效配置

Description
描述

int
usb_set_configuration( usb_dev_handle *dev,
                       int             configuration );

usb_set_configuration sets the active configuration of a device.
usb_set_configuration 设置一个设备的有效的配置。

The configuration parameter is the value as specified
in the descriptor field bConfigurationValue.
参数 configuration 是作为 usb_config_descriptor 结构体 bConfigurationValue 成员变量的值。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

// Configuration descriptor information.. */
#define USB_MAXCONFIG        8
struct usb_config_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int16_t wTotalLength;
    u_int8_t  bNumInterfaces;
    u_int8_t  bConfigurationValue;
    u_int8_t  iConfiguration;
    u_int8_t  bmAttributes;
    u_int8_t  MaxPower;

    struct usb_interface *interface;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

#define USB_MAXALTSETTING    128    // Hard limit */
struct usb_interface {
    struct usb_interface_descriptor *altsetting;

    int num_altsetting;
};

// Interface descriptor */
#define USB_MAXINTERFACES    32
struct usb_interface_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bInterfaceNumber;
    u_int8_t  bAlternateSetting;
    u_int8_t  bNumEndpoints;
    u_int8_t  bInterfaceClass;
    u_int8_t  bInterfaceSubClass;
    u_int8_t  bInterfaceProtocol;
    u_int8_t  iInterface;

    struct usb_endpoint_descriptor *endpoint;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

// Endpoint descriptor */
#define USB_MAXENDPOINTS    32
struct usb_endpoint_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bEndpointAddress;
    u_int8_t  bmAttributes;
    u_int16_t wMaxPacketSize;
    u_int8_t  bInterval;
    u_int8_t  bRefresh;
    u_int8_t  bSynchAddress;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

Name
名字

usb_set_altinterface -- Sets the active alternate setting of the current interface
                        设置当前接口的有效的替代设置

Description
描述

int
usb_set_altinterface(　usb_dev_handle *dev,
　　　　　　　　　　　　　　int             alternate );

usb_set_altinterface sets the active alternate setting of the current interface.
usb_set_altinterface 设置当前接口的有效的替代设置。

The alternate parameter is the value as specified in the descriptor field bAlternateSetting.
参数 alternate 是作为 usb_interface_descriptor 结构体 bAlternateSetting 成员变量的值。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

// Interface descriptor */
#define USB_MAXINTERFACES    32
struct usb_interface_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bInterfaceNumber;
    u_int8_t  bAlternateSetting;
    u_int8_t  bNumEndpoints;
    u_int8_t  bInterfaceClass;
    u_int8_t  bInterfaceSubClass;
    u_int8_t  bInterfaceProtocol;
    u_int8_t  iInterface;

    struct usb_endpoint_descriptor *endpoint;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

// Endpoint descriptor */
#define USB_MAXENDPOINTS    32
struct usb_endpoint_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bEndpointAddress;
    u_int8_t  bmAttributes;
    u_int16_t wMaxPacketSize;
    u_int8_t  bInterval;
    u_int8_t  bRefresh;
    u_int8_t  bSynchAddress;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

Name
名字

usb_resetep -- Resets state for an endpoint
               重置一个端点的状态

Description
描述

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

usb_resetep resets all state (like toggles) for the specified endpoint.
usb_resetep 为指定的端点重置全部状态(像：开关)。

The ep parameter is the value specified in the descriptor field bEndpointAddress.
参数 ep 是作为 usb_endpoint_descriptor 结构体 bEndpointAddress 成员变量的值。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

Deprecated: usb_resetep is deprecated.
不推荐：usb_resetep 是已废弃了。

You probably want to use usb_clear_halt.
你可能需要使用 use usb_clear_halt 函数来代替。

// Endpoint descriptor */
#define USB_MAXENDPOINTS    32
struct usb_endpoint_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bEndpointAddress;
    u_int8_t  bmAttributes;
    u_int16_t wMaxPacketSize;
    u_int8_t  bInterval;
    u_int8_t  bRefresh;
    u_int8_t  bSynchAddress;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

Name
名字

usb_clear_halt -- Clears any halt status on an endpoint
                  在一个端点上清除任何停止状态

Description
描述

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

usb_clear_halt clears any halt status on the specified endpoint.
usb_clear_halt 清除指定端点上的任何停止状态。

The ep parameter is the value specified in the descriptor field bEndpointAddress.
参数 ep 是作为 usb_endpoint_descriptor 结构体 bEndpointAddress 成员变量的值。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

// Endpoint descriptor */
#define USB_MAXENDPOINTS    32
struct usb_endpoint_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bEndpointAddress;
    u_int8_t  bmAttributes;
    u_int16_t wMaxPacketSize;
    u_int8_t  bInterval;
    u_int8_t  bRefresh;
    u_int8_t  bSynchAddress;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

Name
名字

usb_reset -- Resets a device
             重置一个设备

Description
描述

int
usb_reset( usb_dev_handle* dev );

usb_reset resets the specified device by sending a RESET down the port it is connected to.
usb_reset 通过已连接到的端口下发一个 RESET 来重置指定的设备。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

Causes re-enumeration:
引起重新枚举：

After calling usb_reset,
the device will need to re-enumerate and thusly,
requires you to find the new device and open a new handle.
调用 usb_reset 之后，设备将需要重新枚举，需要你去找到新设备和打开一个新句柄。

The handle used to call usb_reset will no longer work.
作为参数 dev 指向的句柄在调用过 usb_reset 后将不再有效。

Name
名字

usb_claim_interface -- Claim an interface of a device
                       索取一个设备的一个接口

Description
描述

int
usb_claim_interface( usb_dev_handle* dev,
                     int             interface );

usb_claim_interface claims the interface with the Operating System.
usb_claim_interface 利用操作系统索取接口。

The interface parameter is the value as specified in the descriptor field bInterfaceNumber.
参数 interface 是作为 usb_interface_descriptor 结构体的 bInterfaceNumber 成员变量的值。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

Must be called!:
必须被调用：

usb_claim_interface must be called before you perform any operations related to this interface
(like usb_set_altinterface, usb_bulk_write, etc).
usb_claim_interface 必须是在你执行任何与该接口有关系的操作前被调用
(像 usb_set_altinterface 、usb_bulk_write 等等之前)。

Table 1. Return Codes
表一：返回码
 code  description
返回码  描述
EBUSY  Interface is not available to be claimed
       被索取的接口不是可用的    
ENOMEM Insufficient memory
       内存不足

// Interface descriptor */
#define USB_MAXINTERFACES    32
struct usb_interface_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bInterfaceNumber;
    u_int8_t  bAlternateSetting;
    u_int8_t  bNumEndpoints;
    u_int8_t  bInterfaceClass;
    u_int8_t  bInterfaceSubClass;
    u_int8_t  bInterfaceProtocol;
    u_int8_t  iInterface;

    struct usb_endpoint_descriptor *endpoint;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

// Endpoint descriptor */
#define USB_MAXENDPOINTS    32
struct usb_endpoint_descriptor {
    u_int8_t  bLength;
    u_int8_t  bDescriptorType;
    u_int8_t  bEndpointAddress;
    u_int8_t  bmAttributes;
    u_int16_t wMaxPacketSize;
    u_int8_t  bInterval;
    u_int8_t  bRefresh;
    u_int8_t  bSynchAddress;

    unsigned char *extra;    // Extra descriptors */
    int extralen;
};

Name
名字

usb_release_interface -- Releases a previously claimed interface
                         释放一个之前索取的接口

Description
描述

int
usb_release_interface( usb_dev_handle* dev,
                       int             interface );

usb_release_interface releases an interface previously claimed with usb_claim_interface.
usb_release_interface 释放一个之前用 usb_claim_interface 索取的接口。

The interface parameter is the value as specified in the descriptor field bInterfaceNumber.
参数 interface 是作为 usb_interface_descriptor 结构体的 bInterfaceNumber 成员变量的值。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

III. Control Transfers
     libusb 外部接口函数之 控制端点传输 接口函数

This group of functions allow applications to send messages to the default control pipe.
这组函数允许应用程序发送消息到默认控制管道。

Name
名字

usb_control_msg -- Send a control message to a device
                   给一个设备发送一个控制消息

Description
描述

int
usb_control_msg( usb_dev_handle* dev,
                 int             requesttype,
                 int             request,
                 int             value,
                 int             index,
                 char*           bytes,
                 int             size,
                 int             timeout );

usb_control_msg performs a control request to the default control pipe on a device.
usb_control_msg 在一个设备上完成一个控制请求到默认控制管道。

The parameters mirror the types of the same name in the USB specification.
函数的参数对应 USB 规范中的同名类型。

Returns number of bytes written/read or < 0 on error.
成功返回正整数为读写入字节的数量(>0)，出错返回负数(<0)。

Name
名字

usb_get_string -- Retrieves a string descriptor from a device
                  从一个设备检索一个字符串描述符

Description
描述

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

usb_get_string retrieves the string descriptor specified by index and langid from a device.
usb_get_string 通过参数 index 和 langid 从一个设备检索字符串描述符。

The string will be returned in Unicode as specified by the USB specification.
字符串描述符将是按照 USB 规范以 Unicode 编码返回。

Returns the number of bytes returned in buf or < 0 on error.
成功返回正整数为参数 buf 所指向缓冲区中实际字符串描述符所用字节的数量(>0)，出错返回负数(<0)。

Name
名字

usb_get_string_simple -- Retrieves a string descriptor from
                         a device using the first language
                         使用第一语言从一个设备检索一个字符串描述符

Description
描述

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

usb_get_string_simple is a wrapper around usb_get_string that
retrieves the string description specified by index in the first language
for the descriptor and converts it into C style ASCII.
usb_get_string_simple 是一个包裹了 usb_get_string 的函数，
根据参数 index 用描述符的第一语言检索字符串描述，然后转换它为 C 样式的 ASCII 字符串。

Returns number of bytes returned in buf or < 0 on error.
成功返回正整数为参数 buf 所指向缓冲区中实际字符串描述符所用字节的数量(>0)，出错返回负数(<0)。

Name
名字

usb_get_descriptor -- Retrieves a descriptor from
                      a device's default control pipe
                      从一个设备的默认控制管道检索一个字符串描述符

Description
描述

int
usb_get_descriptor( usb_dev_handle* dev,
                    unsigned char   type,
                    unsigned char   index,
                    void*           buf,
                    int             size );

usb_get_descriptor retrieves a descriptor from the device identified
by the type and index of the descriptor from the default control pipe.
usb_get_descriptor 从默认控制管道中按参数(描述符的) type 和 index 确定的设备检索一个描述符。

Returns number of bytes read for the descriptor or < 0 on error.
成功返回正整数，即读到的描述符字节数量(>0)，出错返回负数(<0)。

See usb_get_descriptor_by_endpoint for a function that
allows the control endpoint to be specified.
参见 usb_get_descriptor_by_endpoint 函数，允许指定控制端点。

Name
名字

usb_get_descriptor_by_endpoint -- Retrieves a descriptor from a device
                                  从一个设备检索一个描述符

Description
描述

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

usb_get_descriptor_by_endpoint retrieves a descriptor from the device identified
by the type and index of the descriptor from the control pipe identified by ep.
usb_get_descriptor_by_endpoint 从参数 ep 确定的控制管道中按参数(描述符的) type 和 index
确定的设备检索一个描述符。

Returns number of bytes read for the descriptor or < 0 on error.
成功返回正整数，即读到的描述符字节数量(>0)，出错返回负数(<0)。

IV. Bulk Transfers
    libusb 外部接口函数之 批量端点传输 接口函数

This group of functions allow applications to send and receive data via bulk pipes.
这组函数允许应用程序发送和接收数据通过批量管道。

Name
名字

usb_bulk_write -- Write data to a bulk endpoint
                  写数据到一个批量端点

Description
描述

int
usb_bulk_write( usb_dev_handle* dev,
                int             ep,
                char*           bytes,
                int             size,
                int             timeout );

usb_bulk_write performs a bulk write request to the endpoint specified by ep.
usb_bulk_write 向参数 ep 指定的端点完成一个批量写入请求。

Returns number of bytes written on success or < 0 on error.
成功返回正整数(>0)，即已写入的字节数量，出错返回负数(<0)。

Name
名字

usb_bulk_read -- Read data from a bulk endpoint
                 从一个批量端点读取数据

Description
描述

int
usb_bulk_read( usb_dev_handle* dev,
               int             ep,
               char*           bytes,
               int             size,
               int             timeout );

usb_bulk_read performs a bulk read request to the endpoint specified by ep.
usb_bulk_read 向参数 ep 指定的端点完成一个批量读取请求。

Returns number of bytes read on success or < 0 on error.
成功返回正整数(>0)，即已读取的字节数量，出错返回负数(<0)。

V. Interrupt Transfers
   libusb 外部接口函数之 中断端点传输 接口函数

This group of functions allow applications to send and receive data via interrupt pipes.
这组函数允许应用程序发送和接收数据通过中断管道。

Name
名字

usb_interrupt_write -- Write data to an interrupt endpoint
                       写数据到一个中断端点

Description
描述

int
usb_interrupt_write( usb_dev_handle* dev,
                     int             ep,
                     char*           bytes,
                     int             size,
                     int             timeout );

usb_interrupt_write performs an interrupt write request to the endpoint specified by ep.
usb_interrupt_write 向参数 ep 指定的端点完成一个中断写入请求。

Returns number of bytes written on success or < 0 on error.
成功返回正整数(>0)，即已写入的字节数量，出错返回负数(<0)。

Name
名字

usb_interrupt_read -- Read data from a interrupt endpoint
                      从一个中断端点读取数据

Description
描述

int
usb_interrupt_read( usb_dev_handle* dev,
                    int             ep,
                    char*           bytes,
                    int             size,
                    int             timeout );

usb_interrupt_read performs a interrupt read request to the endpoint specified by ep.
usb_interrupt_read 向参数 ep 指定的端点完成一个中断读取请求。

Returns number of bytes read on success or < 0 on error.
成功返回正整数(>0)，即已读取的字节数量，出错返回负数(<0)。

VI. Non Portable
    libusb 外部接口函数之 不可移植 接口函数

These functions are non portable.
这些函数是不可移植的。

They may expose some part of the USB API on one OS or perhaps a couple, but not all.
它们可能暴露了某个操作系统上的某一部分或许几个 USB 应用程序接口，但不是全部。

They are all marked with the string _np at the end of the function name.
它们是全部在函数名最后部分用 _np 字符串来标明了。

A C preprocessor macro will be defined if the function is implemented.
如果要使这些函数生效，一个 C 预处理器宏将是被定义。

The form is LIBUSB_HAS_ prepended to the function name,
without the leading "usb_", in all caps.
形式是 LIBUSB_HAS_ 为函数名前缀，函数名前的 usb_ 不要了，全部为大写字母。

For example, if usb_get_driver_np is implemented,
LIBUSB_HAS_GET_DRIVER_NP will be defined.
例如：如果要使 usb_get_driver_np 生效的话，则 LIBUSB_HAS_GET_DRIVER_NP 将是被定义。

Name
名字

usb_get_driver_np -- Get driver name bound to interface
                     得到绑定到接口的驱动程序名

Description
描述

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

This function will obtain the name of the driver bound to the interface specified
by the parameter interface and place it into the buffer named name limited to
namelen characters.
该函数将获得绑定到由参数 interface 指定的接口的驱动程序名，
然后将驱动程序名放入参数 name 指向的缓冲区中，
字节长度由参数 namelen 来限制。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

Implemented on Linux only.
仅在 Linux 上实现。

Name
名字

usb_detach_kernel_driver_np -- Detach kernel driver from interface
                               从接口上拆卸掉内核驱动程序

Description

int
usb_detach_kernel_driver_np( usb_dev_handle* dev,
                             int             interface );

This function will detach a kernel driver from the interface specified
by parameter interface.
该函数将从参数 interface 指定的接口拆卸掉一个内核驱动程序。

Applications using libusb can then try claiming the interface.
应用程序使用 libusb 可以届时尝试索取接口。

Returns 0 on success or < 0 on error.
成功返回零(0)，出错返回负数(<0)。

Implemented on Linux only.
仅在 Linux 上实现。

IV. Examples
    例子

There are some nonintuitive parts of libusb v0.1 that aren't difficult,
but are probably easier to understand with some examples.
这里是一些 libusb v0.1 不困难的非直观部分，但是用一些例子可能更容易来理解。

Chapter 8. Basic Examples
第八章：基本例子

Before any communication can occur with a device, it needs to be found.
在任何通信之前一个设备能被发现，它需要被查找过。

This is accomplished by finding all of the busses and then finding all of the devices
on all of the busses:
查找全部总线完成后，再在全部总线上查找全部设备。

struct usb_bus *busses;

usb_init();
usb_find_busses();
usb_find_devices();

busses = usb_get_busses();

After this,
the application should manually loop through all of the busess and all of
the devices and matching the device by whatever criteria is needed:
在这之后，应用程序将手动循环遍历全部的总线和全部的设备，然后按照需要的任何标准匹配设备：

struct usb_bus* bus = NULL;

int c = 0;
int i = 0:
int a = 0;

// ... */

for ( bus = busses;
      NULL != bus;
      bus = bus->next )
{
     struct usb_device* dev = NULL;

     for ( dev = bus->devices;
           NULL != dev;
           dev = dev->next )
     {
          // Check if this device is a printer */
          // 判断设备是不是一个打印机 */
          if ( 7 == dev->descriptor.bDeviceClass )
          {
               // Open the device, claim the interface and do your processing */
               // 打开设备，索取接口然后做你的处理 */
               ...
          }

          // Loop through all of the configurations */
          // 循环遍历全部的配置 */
          for ( c = 0;
                c < dev->descriptor.bNumConfigurations;
                c++ )
          {
               // 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 ( 7 == dev->config[c].interface[i].altsetting[a].bInterfaceClass )
                         {
                              // Open the device, set the alternate setting,
                                 claim the interface and do your processing */
                              // 打开设备，设置交替设置，索取接口，然后你的处理 */
                              ...
                         }
                     }
               }
          }
     }
}

Chapter 9. Examples in the source distribution
第九章：在源码分布包中的例子

The tests directory has a program called testlibusb.c.
在 libusb-0.1.8 目录中的 tests 目录中有一个程序源代码文件叫做 testlibusb.c 。

It simply calls libusb to find all of the devices,
then iterates through all of the devices and prints out the descriptor dump.
它简单地调用了 libusb 来查找全部设备，然后迭代遍历全部设备且打印出描述符。

It's very simple and as a result, it's of limited usefulness in itself.
其结果非常简单，用处有限。

However, it could serve as a starting point for a new program.
无论如何，它将作为一个新程序的开端。

Chapter 10. Other Applications
第十章：其它应用程序

Another source of examples can be obtained from other applications.
其它的源代码例子可以从其它的应用程序中获取。

•gPhoto uses libusb to communicate with digital still cameras.
 gPhoto 使用 libusb 来与数码相机通信。

•rio500 utils uses libusb to communicate with SONICblue Rio 500 Digital Audio Player.
 rio500 实用工具使用 libusb 来与 SONICblue Rio 500 数码音频播放器通信。