Linux libusb

开发教程＜二＞ API编程接口介绍
WCH_PC_Application

一、背景介绍

上一篇博客主要介绍了libusb在linux系统下的详细安装过程，目前新的libusb离线包已经不需要再单独安装libusb-compat资料包了。libusb 较大版本变动以 V1.0 为分界线，访问官网：http://libusb.info 时可以发现文档说明都以 V1.0 为主了。

官网界面清晰明了，分类十分明确，开发者可以直接从网站下载文档，API使用说明，例程等内容。V1.0 相对于之前版本，提供了更丰富的功能和接口，本篇直接基于新版本 libusb 库 API 进行说明与使用介绍。
二、libusb API 参考与特点
介绍

libusb 是一个开源库，允许从用户空间与 USB 设备进行通信。其面向希望通过自己的软件与 USB 外围设备进行通信的应用程序开发人员。在进行开发之前，建议先通过USB规范文档对USB有一定的了解，如描述符、配置、接口、端点、控制/批量/中断/等时传输等。这样在软件操作 USB 设备时才会得心应手。
libusb库特点

支持所有传输类型（控制/批量/中断/等时）
    同步传输（简单）
    异步传输（更复杂，但更强大）
    线程安全（异步接口通常不需要线程处理）
    轻量级的精简 API
    通过 libusb-compat-0.1 转换层兼容 libusb-0.1
    热插拔支持（在某些平台上）。

要开始阅读 API 文档，建议先从不同类别的 libusb 功能的 Module 页面开始。

进行数据传输时需要决定使用同步还是异步数据传输，同步和异步设备 I/O 文档提供了有关此主题的介绍，我们稍后会进行介绍。

一些示例程序可以在 libusb 源代码发行版中的“examples”子目录下找到。 libusb 主页包括使用 libusb 的真实项目示例列表。建议读者直接从例子程序开始，这样可以快速掌握 libusb 的用法并了解相关函数的功能。
三、libusb API列表

编程经验比较丰富的开发者可以直接在安装路径下找到我们编程时需要引用的头文件usb.h，头文件中代码上部分为 usb 协议标准术语的宏定义，中间为相关结构体定义，后半部为编程使用的 API 声明，下面根据 API 功能和使用顺序进行分类描述：
库初始化与反初始化（Library initialization/deinitialization）
void    libusb_set_debug (libusb_context *ctx, int level)
设置libusb调试等级，方便查看调试过程和log信息。
void    libusb_set_log_cb (libusb_context *ctx, libusb_log_cb cb, int mode)
设置log处理程序，libusb 会将其日志消息重定向到提供的回调函数。
int    libusb_set_option (libusb_context *ctx, enum libusb_option option,...)
设置库选项，使用此函数可配置库中的特定选项。
int    libusb_init (libusb_context **context)
初始化 libusb。必须在调用任何其他 libusb 函数之前调用此函数。
void    libusb_exit (libusb_context *ctx)
取消初始化 libusb。应在关闭所有打开的设备后和应用程序终止之前调用。
设备处理和枚举（Device handling and enumeration）
ssize_t    libusb_get_device_list (libusb_context *ctx, libusb_device ***list)
返回当前连接到系统的 USB 设备列表。这是查找要操作的 USB 设备的入口点。
void    libusb_free_device_list (libusb_device **list, int unref_devices)
释放先前使用 libusb_get_device_list() 发现的设备列表。如果设置了 unref_devices 参数，则列表中每个设备的引用计数减 1。
uint8_t    libusb_get_bus_number (libusb_device *dev)
获取设备连接的总线编号。
uint8_t    libusb_get_port_number (libusb_device *dev)
获取设备连接的端口号。
int    libusb_get_port_numbers (libusb_device *dev, uint8_t *port_numbers, int port_numbers_len)
获取指定设备的从根节点开始的所有端口号列表
int    libusb_get_port_path (libusb_context *ctx, libusb_device *dev, uint8_t *port_numbers, uint8_t port_numbers_len)
请使用 libusb_get_port_numbers API 替代
libusb_device *    libusb_get_parent (libusb_device *dev)
从指定设备获取父设备。
uint8_t    libusb_get_device_address (libusb_device *dev)
获取设备在它所连接的总线上的地址。
int    libusb_get_device_speed (libusb_device *dev)
获取设备的协商连接速度，返回码见 libusb_speed。
int    libusb_get_max_packet_size (libusb_device *dev, unsigned char endpoint)
获取特定端点的 wMaxPacketSize 值。
int    libusb_get_max_iso_packet_size (libusb_device *dev, unsigned char endpoint)

基于端点描述符中的 wMaxPacketSize 字段，计算特定端点在 1 个微帧的持续时间内能够发送或接收的最大数据包大小。
libusb_device *    libusb_ref_device (libusb_device *dev)
增加设备的引用计数。
void    libusb_unref_device (libusb_device *dev)
减少设备的引用计数。如果递减操作导致引用计数达到零，则设备将被销毁。
int    libusb_wrap_sys_device (libusb_context *ctx, intptr_t sys_dev, libusb_device_handle **dev_handle)
（不常用，略）
int    libusb_open (libusb_device *dev, libusb_device_handle **dev_handle)
打开设备并获取设备句柄。句柄允许您在相关设备上执行 I/O。
libusb_device_handle *    libusb_open_device_with_vid_pid (libusb_context *ctx, uint16_t vendor_id, uint16_t product_id)
打开特定 idVendor/idProduct 组合的USB设备。
void    libusb_close (libusb_device_handle *dev_handle)
关闭设备句柄。应在应用程序退出之前在所有打开的句柄上调用。
libusb_device *    libusb_get_device (libusb_device_handle *dev_handle)
获取设备句柄关联的 libusb_device 底层设备。
int    libusb_get_configuration (libusb_device_handle *dev_handle, int *config)
确定当前活动配置的 bConfigurationValue。
int    libusb_set_configuration (libusb_device_handle *dev_handle, int configuration)
设置设备的活动配置。这在支持多个配置的USB设备中会用到。
int    libusb_claim_interface (libusb_device_handle *dev_handle, int interface_number)
在给定的设备句柄上声明一个接口。您必须先声明要使用的接口，然后才能在其任何端点上执行 I/O。
int    libusb_release_interface (libusb_device_handle *dev_handle, int interface_number)
释放先前使用 libusb_claim_interface() 声明的接口。您应该在关闭设备句柄之前释放所有声明的接口。
int    libusb_set_interface_alt_setting (libusb_device_handle *dev_handle, int interface_number, int alternate_setting)
激活接口的备用设置。该接口必须先前已使用 libusb_claim_interface() 声明。
int    libusb_clear_halt (libusb_device_handle *dev_handle, unsigned char endpoint)
清除端点的暂停/停止条件。处于停止状态的端点无法接收或发送数据，直到停止条件停止。
int    libusb_reset_device (libusb_device_handle *dev_handle)
执行 USB 复位以重新初始化设备。
int    libusb_kernel_driver_active (libusb_device_handle *dev_handle, int interface_number)
确定内核驱动程序是否在接口上处于活动状态。如果内核驱动程序处于活动状态，则不能声明该接口，并且 libusb 将无法执行 I/O。
int    libusb_detach_kernel_driver (libusb_device_handle *dev_handle, int interface_number)
分离接口和内核驱动程序。如果成功，您将能够声明接口并执行 I/O。
int    libusb_attach_kernel_driver (libusb_device_handle *dev_handle, int interface_number)
重新附加接口的内核驱动程序，该驱动程序之前使用 libusb_detach_kernel_driver() 分离。
int    libusb_set_auto_detach_kernel_driver (libusb_device_handle *dev_handle, int enable)
启用/禁用 libusb 的自动内核驱动程序分离。启用此功能后，libusb 将在声明接口时自动分离接口上的内核驱动程序，并在释放接口时附加它。

标准USB描述符操作（USB descriptors）
int    libusb_get_device_descriptor (libusb_device *dev, struct libusb_device_descriptor *desc)
获取指定设备的USB设备描述符。
int    libusb_get_active_config_descriptor (libusb_device *dev, struct libusb_config_descriptor **config)
获取当前活动配置的 USB 配置描述符。
int    libusb_get_config_descriptor (libusb_device *dev, uint8_t config_index, struct libusb_config_descriptor **config)
根据其索引获取 USB 配置描述符。
int    libusb_get_config_descriptor_by_value (libusb_device *dev, uint8_t bConfigurationValue, struct libusb_config_descriptor **config)
获取具有特定 bConfigurationValue 的 USB 配置描述符。
void    libusb_free_config_descriptor (struct libusb_config_descriptor *config)
释放从如上API获取的USB配置描述符。
int    libusb_get_ss_endpoint_companion_descriptor (libusb_context *ctx, const struct libusb_endpoint_descriptor *endpoint, struct libusb_ss_endpoint_companion_descriptor **ep_comp)
获取端点超高速端点伴随描述符（如果有）。
void    libusb_free_ss_endpoint_companion_descriptor (struct libusb_ss_endpoint_companion_descriptor *ep_comp)
释放超高速端点伴随描述符。
int    libusb_get_bos_descriptor (libusb_device_handle *dev_handle, struct libusb_bos_descriptor **bos)
获取二进制对象存储 (BOS) 描述符这是一个 BLOCKING（阻塞）函数，它将向设备发送请求。
void    libusb_free_bos_descriptor (struct libusb_bos_descriptor *bos)
释放BOS描述符。
int    libusb_get_usb_2_0_extension_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension)
获取 USB 2.0 扩展描述符。
void    libusb_free_usb_2_0_extension_descriptor (struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension)
释放 USB 2.0 扩展描述符。
int    libusb_get_ss_usb_device_capability_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_cap)
获取 SuperSpeed USB 设备功能描述符。
void    libusb_free_ss_usb_device_capability_descriptor (struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap)
释放 SuperSpeed USB 设备功能描述符。
int    libusb_get_container_id_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_container_id_descriptor **container_id)
获取容器 ID 描述符。
void    libusb_free_container_id_descriptor (struct libusb_container_id_descriptor *container_id)
释放容器 ID 描述符
int    libusb_get_string_descriptor_ascii (libusb_device_handle *dev_handle, uint8_t desc_index, unsigned char *data, int length)
以 C 风格的 ASCII 检索字符串描述符。
static int    libusb_get_descriptor (libusb_device_handle *dev_handle, uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
从默认控制管道中检索描述符。
static int    libusb_get_string_descriptor (libusb_device_handle *dev_handle, uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
获取设备字符串描述符。返回的字符串是 Unicode，详见 USB 规范。
设备热插拔事件通知（Device hotplug event notification）
int    libusb_hotplug_register_callback (libusb_context *ctx, int events, int flags, int vendor_id, int product_id, int dev_class, libusb_hotplug_callback_fn cb_fn, void *user_data, libusb_hotplug_callback_handle *callback_handle)
注册热插拔回调函数。
void    libusb_hotplug_deregister_callback (libusb_context *ctx, libusb_hotplug_callback_handle callback_handle)
取消注册热插拔回调。
void *    libusb_hotplug_get_user_data (libusb_context *ctx, libusb_hotplug_callback_handle callback_handle)
获取与热插拔回调关联的 user_data。
异步设备I/O（Asynchronous device I/O）
Functions
int    libusb_alloc_streams (libusb_device_handle *dev_handle, uint32_t num_streams, unsigned char *endpoints, int num_endpoints)
在指定的端点上分配最多 num_streams 个 USB 批量流。
int    libusb_free_streams (libusb_device_handle *dev_handle, unsigned char *endpoints, int num_endpoints)
释放流。
unsigned char *    libusb_dev_mem_alloc (libusb_device_handle *dev_handle, size_t length)
尝试分配适合针对给定设备进行传输的 DMA 内存块。
int    libusb_dev_mem_free (libusb_device_handle *dev_handle, unsigned char *buffer, size_t length)
释放DMA内存块。
struct libusb_transfer *    libusb_alloc_transfer (int iso_packets)
使用指定数量的同步数据包描述符分配 libusb 传输。
void    libusb_free_transfer (struct libusb_transfer *transfer)
释放libusb传输。
int    libusb_submit_transfer (struct libusb_transfer *transfer)
提交一次传输。
int    libusb_cancel_transfer (struct libusb_transfer *transfer)
取消传输。
void    libusb_transfer_set_stream_id (struct libusb_transfer *transfer, uint32_t stream_id)
设置传输批量流ID。
uint32_t    libusb_transfer_get_stream_id (struct libusb_transfer *transfer)
获取传输批量流ID。
static unsigned char *    libusb_control_transfer_get_data (struct libusb_transfer *transfer)
获取控制传输的数据部分。
static struct libusb_control_setup *    libusb_control_transfer_get_setup (struct libusb_transfer *transfer)
获取控制传输的控制Setup包。
static void    libusb_fill_control_setup (unsigned char *buffer, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength)
辅助函数用于填充Setup包（数据缓冲区的前 8 个字节）以进行控制传输。
static void    libusb_fill_control_transfer (struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
用于填充控制传输所需的 libusb_transfer 字段的辅助函数。
static void    libusb_fill_bulk_transfer (struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
用于填充批量传输所需的 libusb_transfer 字段的辅助函数。
static void    libusb_fill_bulk_stream_transfer (struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, uint32_t stream_id, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
使用批量流填充批量传输所需的 libusb_transfer 字段的辅助函数。
static void    libusb_fill_interrupt_transfer (struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
用于填充中断传输所需的 libusb_transfer 字段的辅助函数。
static void    libusb_fill_iso_transfer (struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, int num_iso_packets, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
用于填充同步传输所需的 libusb_transfer 字段的辅助函数。
static void    libusb_set_iso_packet_lengths (struct libusb_transfer *transfer, unsigned int length)
根据传输结构中的 num_iso_packets 字段设置同步传输中所有数据包长度的便捷功能。
static unsigned char *    libusb_get_iso_packet_buffer (struct libusb_transfer *transfer, unsigned int packet)
定位同步数据包在同步传输缓冲区内的位置的便捷功能。
static unsigned char *    libusb_get_iso_packet_buffer_simple (struct libusb_transfer *transfer, unsigned int packet)
定位同步数据包在同步传输缓冲区内的位置的便捷功能，用于每个数据包大小相同的传输。
轮询和计时（Polling and timing）

只有异步 API 的用户才需要这些函数。如果只使用更简单的同步 API，那么不需要调用这些函数。
int    libusb_try_lock_events (libusb_context *ctx)
尝试获取事件处理锁。
void    libusb_lock_events (libusb_context *ctx)
获取事件处理锁，如果有争用则阻塞直到成功获取。
void    libusb_unlock_events (libusb_context *ctx)
释放锁。
int    libusb_event_handling_ok (libusb_context *ctx)
确定该线程是否仍然可以进行事件处理。
int    libusb_event_handler_active (libusb_context *ctx)
确定活动线程是否正在处理事件（即是否有人持有事件处理锁）。
void    libusb_interrupt_event_handler (libusb_context *ctx)
中断正在处理事件的任何活动线程。当应用程序希望调用 libusb_exit() 时，这主要用于中断专用的事件处理线程。
void    libusb_lock_event_waiters (libusb_context *ctx)
获取事件等待者锁。
void    libusb_unlock_event_waiters (libusb_context *ctx)
释放事件等待者锁。
int    libusb_wait_for_event (libusb_context *ctx, struct timeval *tv)
等待另一个线程发出事件完成的信号。
int    libusb_handle_events_timeout_completed (libusb_context *ctx, struct timeval *tv, int *completed)
处理任何挂起事件。
int    libusb_handle_events_timeout (libusb_context *ctx, struct timeval *tv)
处理任何挂起事件。
int    libusb_handle_events (libusb_context *ctx)
在阻塞模式下处理任何挂起的事件。
int    libusb_handle_events_completed (libusb_context *ctx, int *completed)
在阻塞模式下处理任何挂起的事件。
int    libusb_handle_events_locked (libusb_context *ctx, struct timeval *tv)
通过轮询文件描述符处理任何挂起的事件，而不检查是否有任何其他线程已经在这样做。必须在持有事件锁的情况下调用，请参阅 libusb_lock_events()。
int    libusb_pollfds_handle_timeouts (libusb_context *ctx)
确定您的应用程序在监视 libusb 的文件描述符时是否必须应用特殊的时序注意事项。
int    libusb_get_next_timeout (libusb_context *ctx, struct timeval *tv)
确定 libusb 需要处理的下一个内部超时。
void    libusb_set_pollfd_notifiers (libusb_context *ctx, libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb, void *user_data)
为文件描述符添加/删除注册通知函数。将为 libusb 用作事件源的每个新的或删除的文件描述符调用这些函数。
const struct libusb_pollfd **    libusb_get_pollfds (libusb_context *ctx)
检索应由主循环轮询作为 libusb 事件源的文件描述符列表。
void    libusb_free_pollfds (const struct libusb_pollfd **pollfds)
释放 libusb_pollfd 结构的列表。这应该为所有使用 libusb_get_pollfds() 分配的 pollfd 列表调用。
同步设备I/O（Synchronous device I/O）

在进行简单传输可采用如下I/O，高级功能建议使用异步设备 I/O函数集。
int    libusb_control_transfer (libusb_device_handle *dev_handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout)
执行 USB 控制传输。
int    libusb_bulk_transfer (libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)
执行 USB 批量传输。
int    libusb_interrupt_transfer (libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)
执行 USB 中断传输。

————————————————
版权声明：本文为CSDN博主「WCH_PC_Application」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：

Linux libusb相关推荐

linux 查看libusb版本,linux / libusb获取usb设备路径
我使用libusb来枚举一些usb设备.现在我想获得"设备路径".我认为这不是usb device-path,因为我没有成功使用谷歌. 如果我用linux连接usb设备,我会在dm ...
Linux libusb开发教程＜一＞介绍与安装
1.libusb简介 libusb 是一个 C 库,提供对 USB 设备的通用访问. 它旨在供开发人员用于促进与 USB 硬件通信的应用程序的开发.其具有如下特点可移植:使用单个跨平台 API,它提 ...
Linux libusb USB开发（一）—— USB设备基础概念
在终端用户看来,USB设备为主机提供了多种多样的附加功能,如文件传输,声音播放等,但对USB主机来说,它与所有USB设备的接口都是一致的.一个USB设备由3个功能模块组成:USB总线接口.USB逻辑设 ...
linux libusb应用实例,在Linux中使用libusb-1.0作为非root用户访问USB设备
我试图在RHEL5上作为非root用户与USB设备连接.该设备是一个GPIO接口(其文档可在 http://www.xdimax.com/sub20/sub20.html找到),它使用libusb-1 ...
嵌入式linux libusb,使用libusb操作usb的问题
请登录后使用快捷导航没有帐号?注册发表于2008-9-29 21:47 使用libusb操作usb的问题 [复制链接] 本人有一个usb,有驱动,但是不能加载到系统.我用libusb操作它,但 ...
通用usb驱动libusb介绍和使用示例
小知识: sudo insmod /lib/modules/2.6.22-14-generic/kernel/drivers/usb/serial/usbserial.ko vendor=0x8086 ...
libusb ubuntu
libusb 在官网http://libusb.info/可以下载到,如下图: 参考网址 gcc -o testlibusb testlibusb.c -I/usr/local/include/lib ...
java libusb_Windows下的Java访问USB设备解决之道(翻译Java libusb / libusb-win32 wrapper)收...
Java libusb / libusb-win32 封装包概要 Java libusb 封装包是对libsub和libusb-win32 USB library的Jave封装. libusb旨在创 ...
hidapi在linux下编译,HIDAPI
软件简介 HIDAPI 是一个 USB 和蓝牙的 hid 类设备在 Windows.Linux.FreeBSD 和 Mac 的 C 语言通用库,使用 HIDAPI 可以在 Windows.Linux. ...

Linux libusb

Linux libusb相关推荐

最新文章

热门文章