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
數碼音頻播放器通信。
libusb 開發者指南-牛勝超（轉）
免責聲明！
本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。