libusb 开发者指南-牛胜超（转）

源：libusb 开发者指南

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
数码音频播放器通信。