1. 概述

1.1 介紹

libusb 是一個使用 C 編寫的庫，它提供 USB 設備的通用的訪問方法。APP 通過它，可以方便地訪問 USB 設備，無需編寫 USB 設備驅動程序。

可移植性：支持 Linux、macOS、Windows、Android、OpenBSD 等

用戶模式：APP 不需要特權模式、也不需要提升自己的權限即可訪問 USB 設備

支持所有 USB 協議：從 1.0 到 3.1 都支持

libusb 支持所有的傳輸類型(控制/批量/中斷/實時)，有兩類 API 接口：同步(Synchronous，簡單)，異步(Asynchronous，復雜但是更強大)。

它是輕量級的、線程安全的。還支持熱拔插。

1.2 用法

可以通過 libusb 訪問 USB 設備，不需要 USB 設備端的驅動程序，需要移除原來的驅動程序。然后就可以直接訪問 USB 控制器的驅動程序，使用 open/read/write/ioctl/close 這些接口來打開設備、收發數據、關閉設備。

libusb 封裝了更好用的函數，這些函數的使用可以分為 5 個步驟：

初始化

打開設備

移除原驅動/認領接口

傳輸

關閉設備

2. API 接口

2.1 分類

libusb 的接口函數分為兩類：同步(Synchronous device I/O)、異步(Asynchronous device I/O)。

USB 數據傳輸分為兩個步驟，對于讀數據，先給設備發出數據的請求，一段時間后數據返回；對于寫數據，先發送數據給設備，一段時間后得到回應。

同步接口的核心在于把上述兩個步驟放在一個函數里面。比如想去讀取一個 USB 鍵盤的數據，給鍵盤發出讀請求后，如果用戶一直沒有按下鍵盤，那么讀函數會一直等待。

異步接口的核心在于把上述兩個步驟分開：使用一個非阻塞的函數啟動傳輸，它會立刻返回；提供一個回調函數用來處理返回結果。

同步接口的示例代碼如下，在libusb_bulk_transfer函數內部，如果沒有數據則會休眠：

unsignedchardata[4];
intactual_length;
intr=libusb_bulk_transfer(dev_handle,LIBUSB_ENDPOINT_IN,data,sizeof(data),&actual_length,0);
if(r==0&&actual_length==sizeof(data)){
//接收到的數據保存在data數組里
//解析這些數據就可以知道按鍵狀態
}else{
error();
}使用同步接口時，代碼比較簡單。但是無法實現"多 endpoint"的操作：上一個 endpoint 的傳輸在休眠，除非使用另一個線程，否則在同一個線程內部在等待期間是無法操作另一個 endpoint 的。還有另一個缺點：無法取消傳輸。

異步接口是在 libusb-1.0 引入的新性能，接口更復雜，但是功能更強大。在異步接口函數里，它啟動傳輸、設置回調函數后就立刻返回。等"讀到數據"或是"得到回應"后，回調函數被調用。發起數據傳輸的線程無需休眠等待結果，它支持"多endpoint"的操作，也支持取消傳輸。

2.2 初始化/反初始化

/**ingrouplibusb_lib
*初始化libusb，這個函數必須先于其他libusb的函數執行
*
*如果傳入NULL，那么函數內部會穿件一個默認的context
*如果已經創建過默認的context，這個context會被重新使用(不會重新初始化它)
*
*參數：
*ctx:contextpointer的位置，也可以傳入NULL
*返回值
*0-成功
*負數-失敗
*/
intAPI_EXPORTEDlibusb_init(libusb_context**ctx);

初始化 libusb，參數是一個"a context pointer"的指針，如果這個參數為 NULL，則函數內部會創建一個"default context"。所謂"libusb context"就是 libusb 上下文，就是一個結構體，里面保存有各類信息，比如：libusb 的調試信息是否需要打印、各種互斥鎖、各類鏈表(用來記錄USB傳輸等等)。

程序退出前，調用如下函數：

/**ingrouplibusb_lib
*發初始化libusb
*在關閉usb設備(libusb_close)后、退出程序前調用此函數
*
*參數:
*ctx:context,傳入NULL表示defaultcontext
*/
voidAPI_EXPORTEDlibusb_exit(libusb_context*ctx);

2.3 獲取設備

可以使用libusb_get_device_list取出所有設備，函數接口如下：

/**@ingrouplibusb_dev
*返回一個list，list里含有當前系統中所有的USB設備
*
*我們一般會在list里尋找需要訪問的設備，找到之后使用libusb_open函數打開它
*然后調用libusb_free_device_list釋放list
*
*這個函數的返回值表示list中有多少個設備
*list的最后一項是NULL
*
*參數:
*ctx:context
*list:outputlocationforalistofdevices,最后必須調用libusb_free_device_list()來釋放它
*返回值:list中設備的個數,或錯誤值
*/
ssize_tAPI_EXPORTEDlibusb_get_device_list(libusb_context*ctx,libusb_device***list);

調用此函數后，所有設備的信息存入 list，然后遍歷 list，找到想操作的設備。這個函數內部會分配 list 的空間，所以用完后要釋放掉，使用以下函數釋放：

/**ingrouplibusb_dev
*前面使用libusb_get_device_list()獲得了設備list,
*使用完后要調用libusb_free_device_list()釋放這個list
*如果參數unref_devices為1,則list中每個設備的引用計數值減小1
*參數:
*list:要釋放的設備list
*unref_devices:是否要將設備的引用計數減1
*/
voidAPI_EXPORTEDlibusb_free_device_list(libusb_device**list,intunref_devices);

2.4 打開/關閉設備

使用 libusb_get_device_list 得到設備列表后，可以選擇里面的某個設備，然后調用 libusb_open：

/**ingrouplibusb_dev
*打開一個設備并得到它的句柄,以后進行IO操作時都是使用句柄
*
*使用libusb_get_device()函數可以得到設備的list,
*從list里確定你要訪問的設備后, 使用libusb_open()去打開它。
* libusb_open()函數內部會增加此設備的引用計數, 使用完畢后要調用libusb_close()減小引用計數。
*
*參數:
*dev:要打開的設備
*dev_handle:輸出參數,用來保存句柄
*返回值:
*0-成功
*LIBUSB_ERROR_NO_MEM:缺少內存
*LIBUSB_ERROR_ACCESS:權限不足
*LIBUSB_ERROR_NO_DEVICE:這個設備未連接
*其他錯誤:其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_open(libusb_device*dev,libusb_device_handle**dev_handle);

使用 libusb_open 函數打開 USB 設備后，可以得到一個句柄：libusb_device_handle。以后調用各種數據傳輸函數時，就是使用libusb_device_handle。

使用完畢后，調用 libusb_close 關閉設備，函數原型如下：

/**ingrouplibusb_dev
*關閉設備句柄,在程序退出之前應該使用它去關閉已經打開的句柄
*
*設備的引用計數在前面被libusb_open()函數增加了。
*在libusb_close()函數的內部，它會減小設備的引用計數。
*
*參數:dev_handle-句柄
*/
voidAPI_EXPORTEDlibusb_close(libusb_device_handle*dev_handle);

2.5 根據 ID 打開設備

如果知道設備的 VID、PID，那么可以使用 libusb_open_device_with_vid_pid 來找到它、打開它。這個函數的內部，先使用libusb_get_device_list列出所有設備，然后遍歷它們根據 ID 選出設備，接著調用 libusb_open 打開它，最后調用 libusb_free_device_list 釋放設備。

libusb_open_device_with_vid_pid 函數原型如下：

/**ingrouplibusb_dev
*打開設備的常規做法是使用libusb_get_device_list()得到設備list，
*然后遍歷list，找到設備
*接著使用libusb_open()函數得到句柄
*
*如果知道USB設備的VID、PID，那么可以使用libusb_open_device_with_vid_pid()函數快速打開它，得到句柄。
*
*這個函數有一個缺點:如果系統中有多個ID相同的設備，你只能打開第1個設備
*
*參數:
*ctx:context,或者傳入NULL以使用默認的context
*vendor_id:廠家ID
*product_id:產品ID
*
*返回值:
*句柄-找到的第1個設備的句柄
*NULL-沒有找到設備
*/
DEFAULT_VISIBILITY
libusb_device_handle*LIBUSB_CALLlibusb_open_device_with_vid_pid(
libusb_context*ctx,uint16_tvendor_id,uint16_tproduct_id);

2.6 描述符相關函數

2.6.1 獲得設備描述符

/**ingrouplibusb_desc
*獲得設備描述符
*
*參數:
*dev-哪個設備
*desc-輸出參數,用來保存設備描述符
*
*返回值:
*0-成功,或其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_get_device_descriptor(libusb_device*dev,
structlibusb_device_descriptor*desc);

2.6.2 獲得/釋放配置描述符

/**ingrouplibusb_desc
*獲得指定的配置描述符
*
*參數:
*dev-哪個設備
*config_index-哪個配置
*config-輸出參數,用來保存配置描述符,使用完畢要調用libusb_free_config_descriptor()釋放掉
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-沒有這個配置
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_get_config_descriptor(libusb_device*dev,
uint8_tconfig_index,structlibusb_config_descriptor**config);

/**ingrouplibusb_desc
*Freeaconfigurationdescriptorobtainedfrom
*前面使用libusb_get_active_config_descriptor()或libusb_get_config_descriptor()獲得配置描述符，
*用完后調用libusb_free_config_descriptor()釋放掉
*/
voidAPI_EXPORTEDlibusb_free_config_descriptor(
structlibusb_config_descriptor*config);

2.7 detach/attach 驅動

2.7.1 兩種方法

使用 libusb 訪問 USB 設備時，需要先移除(detach)設備原來的驅動程序，然后認領接口(claim interface)。有兩種辦法：

方法1：

//只是設置一個標記位表示libusb_claim_interface
//使用libusb_claim_interface時會detach原來的驅動
libusb_set_auto_detach_kernel_driver(hdev,1);

//標記這個interface已經被使用認領了
libusb_claim_interface(hdev,interface_number);

方法2：

//detach原來的驅動
libusb_detach_kernel_driver(hdev,interface_number);

//標記這個interface已經被使用認領了
libusb_claim_interface(hdev,interface_number);

2.7.2 函數原型

函數libusb_detach_kernel_driver原型如下：

/**ingrouplibusb_dev
*給USB設備的接口(interface)移除驅動程序.Ifsuccessful,youwillthenbe
*移除原來的驅動后才能"claimtheinterface"、執行IO操作
*
*實際上libusb會給這個接口安裝一個特殊的內核驅動,
*所以本函數"移除驅動"是移除其他驅動，不是移除這個特殊的驅動。
*若干這個接口已經安裝了這個特殊的驅動，本函數會返回LIBUSB_ERROR_NOT_FOUND.
*
*參數:
*dev_handle-設備句柄
*interface_number-哪一個接口
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-這個接口沒有安裝其他驅動
*LIBUSB_ERROR_INVALID_PARAM-沒有這個接口
*LIBUSB_ERROR_NO_DEVICE-這個設備未連接
*LIBUSB_ERROR_NOT_SUPPORTED-系統不支持此操作,比如Windows
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_detach_kernel_driver(libusb_device_handle*dev_handle,intinterface_number);

函數libusb_claim_interface原型如下：

/**ingrouplibusb_dev
*libusb使用內核里一個特殊的驅動程序，
*libusb_claim_interface()函數就是給某個usb接口安裝這個特殊的驅動程序，
*在使用libusb的函數執行IO操作之前必須調用本函數。
*
*你可以給"已經claim過的接口"再次調用本函數，它直接返回0。
*
*如果這個接口的auto_detach_kernel_driver被設置為1，
* libusb_claim_interface()函數會先移除其他驅動。
*
*本函數時純粹的邏輯操作：只是替換接口的驅動程序而已，不會導致USB硬件傳輸。
*
*參數:
*dev_handle-句柄,表示USB設備
*interface_number-接口
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-沒有這個接口
*LIBUSB_ERROR_BUSY-其他APP或者驅動正在使用這個接口
*LIBUSB_ERROR_NO_DEVICE-設備未連接
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_claim_interface(libusb_device_handle*dev_handle,intinterface_number);

使用完 USB 設備后，在調用 libusb_close 之前，應該libusb_release_interface釋放接口：

/**ingrouplibusb_dev
*前面使用libusb_claim_interface()給接口安裝了給libusb使用的特殊驅動程序,
*使用完畢后，在調用libusb_close()關閉句柄之前，
*可以調用libusb_release_interface()卸載特殊驅動程序
*如果設備的auto_detach_kernel_driver為1，還會重新安裝普通驅動程序
*
*這是一個阻塞函數,它會給USB設備發送一個請求:SET_INTERFACEcontrol,
*用來把接口的狀態復位到第1個setting(thefirstalternatesetting)
*
*參數:
*dev_handle-設備句柄
*interface_number-哪個接口
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-這個接口沒有被claim(沒有安裝特殊的驅動程序)
*LIBUSB_ERROR_NO_DEVICE-設備未連接
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_release_interface(libusb_device_handle*dev_handle,intinterface_number);

2.8 同步傳輸函數

2.8.1 控制傳輸

/**ingrouplibusb_syncio
*啟動控制傳輸
*
*傳輸方向在bmRequestType里
*wValue,wIndex和wLength是host-endian字節序
*
*參數:
*dev_handle-設備句柄
*bmRequestType-setup數據包的bmRequestType域
*bRequest-setup數據包的bRequest域
*wValue-setup數據包的wValue域
*wIndex-setup數據包的wIndex域
*data-保存數據的buffer,可以是in、out數據
*wLength-setup數據包的wLength域
*timeout-超時時間(單位ms)，就是這個函數能等待的最大時間;0表示一直等待直到成功
*
*返回值:
*正整數-成功傳輸的數據的長度
*LIBUSB_ERROR_TIMEOUT-超時
*LIBUSB_ERROR_PIPE-設備不支持該請求
*LIBUSB_ERROR_NO_DEVICE-設備未連接
*LIBUSB_ERROR_BUSY-如果這個函數時在事件處理上下文(eventhandlingcontext)里則返回這個錯誤
*LIBUSB_ERROR_INVALID_PARAM-傳輸的字節超過OS或硬件的支持
*theoperatingsystemand/orhardwarecansupport(see
efasynclimits)
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_control_transfer(libusb_device_handle*dev_handle,
uint8_tbmRequestType,uint8_tbRequest,uint16_twValue,uint16_twIndex,
unsignedchar*data,uint16_twLength,unsignedinttimeout);

2.8.2 批量傳輸

/**ingrouplibusb_syncio
*啟動批量傳輸
*傳輸方向在endpoint的"方向位"里表示
*
*對于批量讀，參數length表示"期望讀到的數據最大長度",實際讀到的長度保存在transferred參數里
*
*對于批量寫,transferred參數表示實際發送出去的數據長度
*
*發生超時錯誤時，也應該檢查transferred參數。
*libusb會根據硬件的特點把數據拆分為一小段一小段地發送出去，
*這意味著發送滿某段數據后可能就發生超時錯誤，需要根據transferred參數判斷傳輸了多少數據。
*
*參數:
*dev_handle-設備句柄
*endpoint-端點
*data-保存數據的buffer,可以是in、out數據
*length-對于批量寫，它表示要發送的數據長度;對于批量讀，它表示"要讀的數據的最大長度"
*transferred-輸出參數，表示實際傳輸的數據長度
*timeout-超時時間(單位ms)，就是這個函數能等待的最大時間;0表示一直等待直到成功
*
*返回值:
*0-成功，根據transferred參數判斷傳輸了多少長度的數據
*LIBUSB_ERROR_TIMEOUT-超時,根據transferred參數判斷傳輸了多少長度的數據
*LIBUSB_ERROR_PIPE-端點錯誤，端點被掛起了
*LIBUSB_ERROR_OVERFLOW-溢出，設備提供的數據太多了
*LIBUSB_ERROR_NO_DEVICE-設備未連接
*LIBUSB_ERROR_BUSY-如果這個函數時在事件處理上下文(eventhandlingcontext)里則返回這個錯誤
*LIBUSB_ERROR_INVALID_PARAM-傳輸的字節超過OS或硬件的支持
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_bulk_transfer(libusb_device_handle*dev_handle,
unsignedcharendpoint,unsignedchar*data,intlength,
int*transferred,unsignedinttimeout);

2.8.3 中斷傳輸

/**ingrouplibusb_syncio
*啟動中斷傳輸
*傳輸方向在endpoint的"方向位"里表示
*
*對于中斷讀，參數length表示"期望讀到的數據最大長度",實際讀到的長度保存在transferred參數里
*
*對于中斷寫, transferred參數表示實際發送出去的數據長度，不一定能發送完全部數據。
*
*發生超時錯誤時，也應該檢查transferred參數。
*libusb會根據硬件的特點把數據拆分為一小段一小段地發送出去，
*這意味著發送滿某段數據后可能就發生超時錯誤，需要根據transferred參數判斷傳輸了多少數據。
*
*參數:
*dev_handle-設備句柄
*endpoint-端點
*data-保存數據的buffer,可以是in、out數據
*length-對于批量寫，它表示要發送的數據長度;對于批量讀，它表示"要讀的數據的最大長度"
*transferred-輸出參數，表示實際傳輸的數據長度
*timeout-超時時間(單位ms)，就是這個函數能等待的最大時間;0表示一直等待直到成功
*
*返回值:
*0-成功，根據transferred參數判斷傳輸了多少長度的數據
*LIBUSB_ERROR_TIMEOUT-超時,根據transferred參數判斷傳輸了多少長度的數據
*LIBUSB_ERROR_PIPE-端點錯誤，端點被掛起了
*LIBUSB_ERROR_OVERFLOW-溢出，設備提供的數據太多了
*LIBUSB_ERROR_NO_DEVICE-設備未連接
*LIBUSB_ERROR_BUSY-如果這個函數時在事件處理上下文(eventhandlingcontext)里則返回這個錯誤
*LIBUSB_ERROR_INVALID_PARAM-傳輸的字節超過OS或硬件的支持
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_interrupt_transfer(libusb_device_handle*dev_handle,
unsignedcharendpoint,unsignedchar*data,intlength,
int*transferred,unsignedinttimeout);

2.9 異步傳輸函數

2.9.1 使用步驟

使用 libusb 的異步函數時，有如下步驟：

分配：分配一個libusb_transfer結構體

填充：填充libusb_transfer結構體，比如想訪問哪個 endpoint、數據 buffer、長度等等

提交：提交libusb_transfer結構體啟動傳輸

處理事件：檢查傳輸的結果，調用libusb_transfer結構體的回調函數

釋放：釋放資源，比如釋放libusb_transfer結構體

2.9.2 分配 transfer 結構體

/**ingrouplibusb_asyncio
*分配一個libusb_transfer結構體，
*如果iso_packets不為0，還會分配iso_packets個libusb_iso_packet_descriptor結構體
*使用完畢后需要調用libusb_free_transfer()函數釋放掉
*
*對于控制傳輸、批量傳輸、中斷傳輸，iso_packets參數需要設置為0
*
*對于實時傳輸，需要指定iso_packets參數，
*這個函數會一起分配iso_packets個libusb_iso_packet_descriptor結構體。
*這個函數返回的libusb_transfer結構體并未初始化，
*你還需要初始化它的這些成員:
*libusb_transfer::num_iso_packets
*libusb_transfer::type
*
*你可以指定iso_packets參數，意圖給實時傳輸分配結構體，
*但是你可以把這個結構題用于其他類型的傳輸，
*在這種情況下，只要確保num_iso_packets為0就可以。
*
*參數:
*iso_packets-分配多少個isochronouspacketdescriptorstoallocate
*
*返回值:
*返回一個libusb_transfer結構體或NULL
*/
DEFAULT_VISIBILITY
structlibusb_transfer*LIBUSB_CALLlibusb_alloc_transfer(intiso_packets);

2.9.3 填充控制傳輸

/**ingrouplibusb_asyncio
*構造控制傳輸結構體
*
*如果你傳入buffer參數，那么buffer的前面8字節會被當做"controlsetuppacket"來解析，
*buffer的最后2字節表示wLength，它也會被用來設置libusb_transfer::length
*所以，建議使用流程如下:
*1.分配buffer，這個buffer的前面8字節對應"controlsetuppacket"，后面的空間可以用來保存其他數據
*2.設置"controlsetuppacket"，通過調用libusb_fill_control_setup()函數來設置
*3.如果是要把數據發送個設備，把要發送的數據放在buffer的后面(從buffer[8]開始放)
*4.調用libusb_fill_bulk_transfer
*5.提交傳輸:調用libusb_submit_transfer()
*
*也可以讓buffer參數為NULL，
*這種情況下libusb_transfer::length就不會被設置,
*需要手工去設置ibusb_transfer::buffer、ibusb_transfer::length
*
*參數:
*transfer-要設置的libusb_transfer結構體
*dev_handle-設備句柄
*buffer-數據buffer，如果不是NULL的話，它前面8直接會被當做"controlsetuppacket"來處理，
*也會從buffer[6],buffer[7]把length提取出來，用來設置libusb_transfer::length
*這個buffer必須是2字節對齊
*callback-傳輸完成時的回調函數
*user_data-傳給回調函數的參數
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_control_transfer(
structlibusb_transfer*transfer,libusb_device_handle*dev_handle,
unsignedchar*buffer,libusb_transfer_cb_fncallback,void*user_data,
unsignedinttimeout);

2.9.4 填充批量傳輸

/**ingrouplibusb_asyncio
*構造批量傳輸結構體
*
*參數:
*transfer-要設置的libusb_transfer結構體
*dev_handle-設備句柄
*endpoint-端點
*buffer-數據buffer
*length-buffer的數據長度
*callback-傳輸完成時的回調函數
*user_data-傳給回調函數的參數
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_bulk_transfer(structlibusb_transfer*transfer,
libusb_device_handle*dev_handle,unsignedcharendpoint,
unsignedchar*buffer,intlength,libusb_transfer_cb_fncallback,
void*user_data,unsignedinttimeout);

2.9.5 填充中斷傳輸

/**ingrouplibusb_asyncio
*構造中斷傳輸結構體
*
*參數:
*transfer-要設置的libusb_transfer結構體
*dev_handle-設備句柄
*endpoint-端點
*buffer-數據buffer
*length-buffer的數據長度
*callback-傳輸完成時的回調函數
*user_data-傳給回調函數的參數
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_interrupt_transfer(
structlibusb_transfer*transfer,libusb_device_handle*dev_handle,
unsignedcharendpoint,unsignedchar*buffer,intlength,
libusb_transfer_cb_fncallback,void*user_data,unsignedinttimeout);

2.9.6 填充實時傳輸

/**ingrouplibusb_asyncio
*構造實時傳輸結構體
*
*參數:
*transfer-要設置的libusb_transfer結構體
*dev_handle-設備句柄
*endpoint-端點
*buffer-數據buffer
*length-buffer的數據長度
*num_iso_packets-實時傳輸包的個數
*callback-傳輸完成時的回調函數
*user_data-傳給回調函數的參數
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_iso_transfer(structlibusb_transfer*transfer,
libusb_device_handle*dev_handle,unsignedcharendpoint,
unsignedchar*buffer,intlength,intnum_iso_packets,
libusb_transfer_cb_fncallback,void*user_data,unsignedinttimeout);

2.9.7 提交傳輸

/**ingrouplibusb_asyncio
*提交傳輸Submit，這個函數會啟動傳輸，然后立刻返回
*
*參數:
*transfer-要傳輸的libusb_transfer結構體
*
*返回值:
*0-成功
*LIBUSB_ERROR_NO_DEVICE-設備未連接
*LIBUSB_ERROR_BUSY-這個傳輸已經提交過了
*LIBUSB_ERROR_NOT_SUPPORTED-不支持這個傳輸
*LIBUSB_ERROR_INVALID_PARAM-傳輸的字節超過OS或硬件的支持
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_submit_transfer(structlibusb_transfer*transfer);

2.9.8 處理事件

有 4 個函數，其中 2 個沒有completed后綴的函數過時了：

/**ingrouplibusb_poll
*處理任何"pengding的事件"
*
*使用異步傳輸函數時，提交的tranfer結構體后就返回了。
*可以使用本函數處理這些傳輸的返回結果。
*
*如果timeval參數為0，本函數會處理"當前、已經pending的事件"，然后馬上返回。
*
*如果timeval參數不為0，并且當前沒有待處理的事件，本函數會阻塞以等待事件，直到超時。
*在等待過程中，如果事件發生了、或者得到了信號(signal)，那么這個函數會提前返回。
*
*completed參數用來避免競爭，如果它不為NULL:
*本函數獲得"eventhandlinglock"后，會判斷completed指向的數值，
*如果這個數值非0(表示別的線程已經處理了、已經completed了)，
*則本函數會立刻返回(既然都completed了，當然無需再處理)
*
*參數:
*ctx-context(如果傳入NULL則使用默認context)
*tv-等待事件的最大時間，0表示不等待
*completed-指針，可以傳入NULL
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events_timeout_completed(libusb_context*ctx,
structtimeval*tv,int*completed);

/**ingrouplibusb_poll
*處理任何"pengding的事件"
*
*跟libusb_handle_events_timeout_completed()類似,
*就是調用"libusb_handle_events_timeout_completed(ctx,tv,NULL);"
*最后的completed參數為NULL。
*
*這個函數只是為了保持向后兼容，新的代碼建議使用libusb_handle_events_completed()或
*libusb_handle_events_timeout_completed()，
*這2個新函數可以處理競爭。
*
*參數:
*ctx-context(如果傳入NULL則使用默認context)
*tv-等待事件的最大時間，0表示不等待
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events_timeout(libusb_context*ctx,structtimeval*tv);

/**ingrouplibusb_poll
*處理任何"pengding的事件"，以阻塞方式處理(blockingmode)
*
*本函數的內部實現就是調用:libusb_handle_events_timeout_completed(ctx,&tv,completed);
*超時時間設置為60秒
*
*參數:
*ctx-context(如果傳入NULL則使用默認context)
*completed-指針，可以傳入NULL
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events_completed(libusb_context*ctx,int*completed);

/**ingrouplibusb_poll
*處理任何"pengding的事件"，以阻塞方式處理(blockingmode)
*
*本函數的內部實現就是調用:libusb_handle_events_timeout_completed(ctx,&tv,NULL);
*超時時間設置為60秒
*
*這個函數只是為了保持向后兼容，新的代碼建議使用libusb_handle_events_completed()或
*libusb_handle_events_timeout_completed()，
*這2個新函數可以處理競爭。
*
*參數:
*ctx-context(如果傳入NULL則使用默認context)
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events(libusb_context*ctx);

2.9.9 釋放 transfer 結構體

傳輸完畢，需要釋放 libusb_transfer 結構體，如果要重復利用這個結構體則無需釋放。

/**ingrouplibusb_asyncio
*釋放libusb_transfer結構體
*前面使用libusb_alloc_transfer()分配的結構體，要使用本函數來釋放。
*
*如果libusb_transfer::flags的LIBUSB_TRANSFER_FREE_BUFFER位非0，
*那么會使用free()函數釋放ibusb_transfer::buffer
*
*不能使用本函數釋放一個活動的傳輸結構體(active,已經提交尚未結束)
*
*/
voidAPI_EXPORTEDlibusb_free_transfer(structlibusb_transfer*transfer);

3. 使用示例

在 libusb 源碼的 examples 目錄下有示例程序，我們也有一些真實的案列。

3.1 dnw 工具

dnw 是 s3c2440 時代的工具，使用它可以從 PC 給開發板傳輸文件。它的核心源碼如下，使用同步接口進行數據傳輸：

/*openthedeviceusinglibusb*/
status=libusb_init(NULL);
if(status

	3.2 openocd

	openocd 是一個開源的 USB JTAG 調試軟件，它也是使用 libusb，涉及 USB 的操作代碼如下。

	3.2.1 找到設備
staticintcmsis_dap_usb_open(structcmsis_dap*dap,uint16_tvids[],uint16_tpids[],constchar*serial)
{
interr;
structlibusb_context*ctx;
structlibusb_device**device_list;

err=libusb_init(&ctx);
if(err){
LOG_ERROR("libusbinitializationfailed:%s",libusb_strerror(err));
returnERROR_FAIL;
}

intnum_devices=libusb_get_device_list(ctx,&device_list);
if(num_devices0){
err=libusb_get_string_descriptor_ascii(
dev_handle,dev_desc.iSerialNumber,
(uint8_t*)dev_serial,sizeof(dev_serial));

if(err0){
err=libusb_get_string_descriptor_ascii(
dev_handle,dev_desc.iProduct,
(uint8_t*)product_string,sizeof(product_string));
if(errbConfigurationValue;
conststructlibusb_interface_descriptor*intf_desc_candidate=NULL;
conststructlibusb_interface_descriptor*intf_desc_found=NULL;

for(intinterface=0;interfacebNumInterfaces;interface++){
conststructlibusb_interface_descriptor*intf_desc=&config_desc->interface[interface].altsetting[0];
intinterface_num=intf_desc->bInterfaceNumber;

/*Skipthisinterfaceifanotheronewasrequestedexplicitly*/
if(cmsis_dap_usb_interface!=-1&&cmsis_dap_usb_interface!=interface_num)
continue;

/*CMSIS-DAPv2specsays:
*
*CMSIS-DAPwithdefaultV2configurationusesWinUSBandisthereforefaster.
*OptionallysupportforstreamingSWOtraceisprovidedviaanadditionalUSBendpoint.
*
*TheWinUSBconfigurationrequirescustomclasssupportwiththeinterfacesetting
*ClassCode:0xFF(Vendorspecific)
*Subclass:0x00
*Protocolcode:0x00
*
*DependingontheconfigurationitusesthefollowingUSBendpointswhichshouldbeconfigured
*intheinterfacedescriptorinthisorder:
*-Endpoint1:BulkOut–usedforcommandsreceivedfromhostPC.
*-Endpoint2:BulkIn–usedforresponsessendtohostPC.
*-Endpoint3:BulkIn(optional)–usedforstreamingSWOtrace(ifenabledwithSWO_STREAM).
*/

/*Searchfor"CMSIS-DAP"intheinterfacestring*/
boolcmsis_dap_in_interface_str=false;
if(intf_desc->iInterface!=0){

charinterface_str[256]={0};

err=libusb_get_string_descriptor_ascii(
dev_handle,intf_desc->iInterface,
(uint8_t*)interface_str,sizeof(interface_str));
if(erriInterface,
dev_desc.idVendor,dev_desc.idProduct,
libusb_strerror(err));
}elseif(strstr(interface_str,"CMSIS-DAP")){
cmsis_dap_in_interface_str=true;
LOG_DEBUG("foundinterface%dstring'%s'",
interface_num,interface_str);
}
}

/*Bypassthefollowingcheckifthisinterfacewasexplicitlyrequested.*/
if(cmsis_dap_usb_interface==-1){
if(!cmsis_dap_in_product_str&&!cmsis_dap_in_interface_str)
continue;
}

/*checkendpoints*/
if(intf_desc->bNumEndpointsbNumEndpoints);
continue;
}

if((intf_desc->endpoint[0].bmAttributes&3)!=LIBUSB_TRANSFER_TYPE_BULK||
(intf_desc->endpoint[0].bEndpointAddress&0x80)!=LIBUSB_ENDPOINT_OUT){
LOG_DEBUG("skippinginterface%d,endpoint[0]isnotbulkout",
interface_num);
continue;
}

if((intf_desc->endpoint[1].bmAttributes&3)!=LIBUSB_TRANSFER_TYPE_BULK||
(intf_desc->endpoint[1].bEndpointAddress&0x80)!=LIBUSB_ENDPOINT_IN){
LOG_DEBUG("skippinginterface%d,endpoint[1]isnotbulkin",
interface_num);
continue;
}

/*WecanrelyontheinterfaceisreallyCMSIS-DAPif
*-we'veseenCMSIS-DAPintheinterfacestring
*-configaskedexplicitlyforaninterfacenumber
*-thedevicehasonlyoneinterface
*Thelatertwocasesshouldbehonoredonlyifweknow
*weareontherightdevice*/
boolintf_identified_reliably=cmsis_dap_in_interface_str
||(device_identified_reliably&&
(cmsis_dap_usb_interface!=-1
||config_desc->bNumInterfaces==1));

if(intf_desc->bInterfaceClass!=LIBUSB_CLASS_VENDOR_SPEC||
intf_desc->bInterfaceSubClass!=0||intf_desc->bInterfaceProtocol!=0){
/*Iftheinterfaceisreliablyidentified
*thenweneednotinsistonsettingUSBclass,subclassandprotocol
*exactlyasthespecificationrequires.
*AtleastKitProg3usesclass0contrarytothespecification*/
if(intf_identified_reliably){
LOG_WARNING("UsingCMSIS-DAPv2interface%dwithwrongclass%"PRId8
"subclass%"PRId8"orprotocol%"PRId8,
interface_num,
intf_desc->bInterfaceClass,
intf_desc->bInterfaceSubClass,
intf_desc->bInterfaceProtocol);
}else{
LOG_DEBUG("skippinginterface%d,class%"PRId8
"subclass%"PRId8"protocol%"PRId8,
interface_num,
intf_desc->bInterfaceClass,
intf_desc->bInterfaceSubClass,
intf_desc->bInterfaceProtocol);
continue;

}
}

if(intf_identified_reliably){
/*That'stheone!*/
intf_desc_found=intf_desc;
break;
}

if(!intf_desc_candidate&&device_identified_reliably){
/*ThisinterfacelookssuitableforCMSIS-DAP.Storethepointertoit
*andkeepsearchingforanotheronewithCMSIS-DAPininterfacestring*/
intf_desc_candidate=intf_desc;
}
}

if(!intf_desc_found){
/*WewerenotabletoidentifyreliablywhichinterfaceisCMSIS-DAP.
*Let'susethefirstsuitableifwefoundone*/
intf_desc_found=intf_desc_candidate;
}

if(!intf_desc_found){
libusb_free_config_descriptor(config_desc);
continue;
}

/*We'vechosenaninterface,connecttoit*/
intinterface_num=intf_desc_found->bInterfaceNumber;
intpacket_size=intf_desc_found->endpoint[0].wMaxPacketSize;
intep_out=intf_desc_found->endpoint[0].bEndpointAddress;
intep_in=intf_desc_found->endpoint[1].bEndpointAddress;

libusb_free_config_descriptor(config_desc);
libusb_free_device_list(device_list,true);

LOG_INFO("UsingCMSIS-DAPv2interfacewithVID:PID=0x%04x:0x%04x,serial=%s",
dev_desc.idVendor,dev_desc.idProduct,dev_serial);

intcurrent_config;
err=libusb_get_configuration(dev_handle,¤t_config);
if(err){
LOG_ERROR("couldnotfindcurrentconfiguration:%s",libusb_strerror(err));
libusb_close(dev_handle);
libusb_exit(ctx);
returnERROR_FAIL;
}

if(config_num!=current_config){
err=libusb_set_configuration(dev_handle,config_num);
if(err){
LOG_ERROR("couldnotsetconfiguration:%s",libusb_strerror(err));
libusb_close(dev_handle);
libusb_exit(ctx);
returnERROR_FAIL;
}
}

err=libusb_claim_interface(dev_handle,interface_num);
if(err)
LOG_WARNING("couldnotclaiminterface:%s",libusb_strerror(err));

dap->bdata=malloc(sizeof(structcmsis_dap_backend_data));
if(!dap->bdata){
LOG_ERROR("unabletoallocatememory");
libusb_release_interface(dev_handle,interface_num);
libusb_close(dev_handle);
libusb_exit(ctx);
returnERROR_FAIL;
}

dap->packet_size=packet_size;
dap->packet_buffer_size=packet_size;
dap->bdata->usb_ctx=ctx;
dap->bdata->dev_handle=dev_handle;
dap->bdata->ep_out=ep_out;
dap->bdata->ep_in=ep_in;
dap->bdata->interface=interface_num;

dap->packet_buffer=malloc(dap->packet_buffer_size);
if(!dap->packet_buffer){
LOG_ERROR("unabletoallocatememory");
cmsis_dap_usb_close(dap);
returnERROR_FAIL;
}

dap->command=dap->packet_buffer;
dap->response=dap->packet_buffer;

returnERROR_OK;
}

libusb_close(dev_handle);
}

libusb_free_device_list(device_list,true);

libusb_exit(ctx);
returnERROR_FAIL;
}

	3.2.2 讀寫數據
staticintcmsis_dap_usb_read(structcmsis_dap*dap,inttimeout_ms)
{
inttransferred=0;
interr;

err=libusb_bulk_transfer(dap->bdata->dev_handle,dap->bdata->ep_in,
dap->packet_buffer,dap->packet_size,&transferred,timeout_ms);
if(err){
if(err==LIBUSB_ERROR_TIMEOUT){
returnERROR_TIMEOUT_REACHED;
}else{
LOG_ERROR("errorreadingdata:%s",libusb_strerror(err));
returnERROR_FAIL;
}
}

memset(&dap->packet_buffer[transferred],0,dap->packet_buffer_size-transferred);

returntransferred;
}

staticintcmsis_dap_usb_write(structcmsis_dap*dap,inttxlen,inttimeout_ms)
{
inttransferred=0;
interr;

/*skipthefirstbytethatisonlyusedbytheHIDbackend*/
err=libusb_bulk_transfer(dap->bdata->dev_handle,dap->bdata->ep_out,
dap->packet_buffer,txlen,&transferred,timeout_ms);
if(err){
if(err==LIBUSB_ERROR_TIMEOUT){
returnERROR_TIMEOUT_REACHED;
}else{
LOG_ERROR("errorwritingdata:%s",libusb_strerror(err));
returnERROR_FAIL;
}
}

returntransferred;
}

	編輯：黃飛