背景介紹

上一篇博文主要介紹了 Libusb 在 Linux 系統下的詳細安裝過程，除了 libusb-1.0.9.tar.bz2 離線包之外，還安裝了 libusb-compat-0.1.4.tar.bz2。顧名思義，第二個是先前版本的相容包，因此在使用過程中，開發者就需要區分引用不同的 lib 版本了。libusb 較大版本變動以 V1.0 為分界線，訪問官網：http://libusb.info 時也可以發現文件說明都以 V1.0 為主了。注意，libusb 已經從 libusb.org 切換到了 libusb.info。展示下最新網站首頁：

分類十分明確，開發者可以直接從網站下載文件，API使用說明，例程等內容。V1.0 相對於之前版本，提供了更豐富的功能和介面，然而大部分情形下舊版本庫提供的 API 函式功能已經可以滿足我們應用的需要了，並且官網的原始碼安裝包一直保持著對於老版本的相容。出於相容性以及大部分開發者使用習慣，本篇先基於老版本 Libusb 庫 API 進行說明與使用介紹。

Libusb API 函式與功能

瞭解包含的 API 函式以及結構體相關定義等很簡單，直接在安裝路徑下找到我們程式設計時需要引用的標頭檔案即可，這裡對應的標頭檔案是 usb.h。我們開啟 usb.h 可以看到，程式碼上部分為 usb 協議標準術語的巨集定義，中間為相關結構體定義，後半部為我們程式設計引用的 API 宣告，下面根據 API 功能和使用順序進行分類描述：

核心初始化函式

1. void usb_init(void);

函式功能：libusb 初始化，這一步必須首先執行。

2. int usb_find_busses(void);

函式功能：查詢系統上的 usb 匯流排，任何 usb 裝置依附於 usb 匯流排和主機通訊。成功返回 usb 匯流排數目，失敗返回負值。

3. int usb_find_devices(void);

函式功能：查詢匯流排上的 usb 裝置，這個函式必須在呼叫 usb_find_busses() 後使用。成功返回裝置數目，失敗返回負值。

4. struct usb_bus *usb_get_busses(void);

函式功能：返回全域性變數 usb_busses，用於遍歷匯流排連結串列，查詢匯流排 usb 裝置。失敗返回 NULL。這四步操作是任何程序必須首先執行的。

裝置操作介面

1. usb_dev_handle *usb_open(struct usb_device *dev);

函式功能：開啟 usb 裝置，引用的 usb_dev_handle 以及 usb_device 結構體是 libusb 最常見的，定義可以參見標頭檔案。函式返回 usb 裝置的操作控制程式碼，之後對該 usb 裝置的操作都通過該控制程式碼進行；

2. int usb_close(usb_dev_handle *dev);

函式功能：關閉 usb 裝置，在所有操作完成後或者程序退出前呼叫，傳入參數即上面提到的控制程式碼，成功返回0；

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

函式功能：獲取裝置的字串描述，通過 index 和 langid 進行索引。返回Unicode字串到buf中，成功返回實際寫入buf 的位元組數，失敗返回負值。

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

函式功能：包裝了 usb_get_string() 函式，返回第一種語言指定 index 索引的字串描述，並轉換到C風格的 ASCII。成功返回實際寫入buf 的位元組數，失敗返回負值。

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

函式功能：從裝置獲取描述符，以 type 和 index 索引，以ep標誌的控制管道。成功返回實際寫入buf 的位元組數，失敗返回負值。

6. int usb_get_descriptor(usb_dev_handle *udev, unsigned char type, unsigned char index, void *buf, int size);

函式功能：獲取裝置預設控制管道的描述符，通過 type 和 index 索引。成功返回實際寫入buf 的位元組數，失敗返回負值。

7. int usb_set_configuration(usb_dev_handle *dev, int configuration);

函式功能：設定當前裝置使用的configuration，引數configuration 是裝置配置描述符中的 bConfigurationValue。成功返回0，失敗返回負值。

8. int usb_claim_interface(usb_dev_handle *dev, int interface);

函式功能： 註冊裝置與作業系統通訊的介面，interface 引數是介面描述符的 bInterfaceNumber 欄位。這個函式必須被呼叫，因為只有註冊介面，才能做相應的操作。必須在任何介面相關操作(如 usb_set_altinterface() 、 usb_bulk_write() 等)之前呼叫。成功返回0，失敗返回負值。

9. int usb_release_interface(usb_dev_handle *dev, int interface);

函式功能：登出在 usb_claim_interface 中註冊的通訊介面，釋放相關資源，與註冊函式成對使用。

10. int usb_set_altinterface(usb_dev_handle *dev, int alternate);

函式功能：設定當前介面中的活躍（起作用的）設定，alternate 為介面描述符中 bAlternateSetting 欄位。成功返回0，失敗返回負值。

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

函式功能：復位指定的端點，引數 ep 為端點描述符中的 bEndpointAddress，此函式已被函式 usb_clear_halt 替代。成功返回0，失敗返回負值。

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

函式功能：復位指定的端點，引數 ep 為端點描述符中的 bEndpointAddress。成功返回0，失敗返回負值。

13. int usb_reset(usb_dev_handle *dev);

函式功能：重置指定裝置，通過傳送 RESET 指令過去。返回0成功，負數失敗。在執行該函式之後，需要重新列舉裝置，且之前的控制程式碼無法再工作。因此現在使用 usb_close 函式來替代。

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

函式功能：獲取裝置介面對應的驅動程式名稱，也即遍歷 sysfs 系統中驅動與裝置的對應關係，查詢當前系統中有無該介面驅動，成功驅動名寫入到 name 中且函式返回0，失敗返回負值。

15. int usb_detach_kernel_driver_np(usb_dev_handle *dev, int interface);

函式功能：從核心中分離該介面驅動程式，也即禁止該驅動對裝置起作用。這個步驟不可省略，不然會發現驅動和使用 Libusb 編寫的應用程式同時對裝置起作用，引起錯誤。使用時可以先通過 usb_get_driver_np 進行判斷，如果有繫結的驅動程式，那麼再呼叫此函式進行分離。成功返回0，失敗返回負值。

資料通訊介面

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

函式功能：批量端點寫函式，傳入指定的端點號，timeout 為超時時間，以 ms 為單位。成功返回實際寫入裝置的位元組數，失敗返回負值。

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

函式功能：批量端點讀函式，傳入指定的端點號，timeout 為超時時間，以 ms 為單位。成功返回實際寫入 buf 的位元組數，失敗返回負值。

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

函式功能：中斷端點寫函式，傳入指定的端點號，timeout 為超時時間，以 ms 為單位。成功返回實際寫入裝置的位元組數，失敗返回負值。

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

函式功能：中斷端點讀函式，傳入指定的端點號，timeout 為超時時間，以 ms 為單位。成功返回實際寫入 buf 的位元組數，失敗返回負值。

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

函式功能：控制請求讀寫函式，傳入引數與 usb 協議保持一致，timeout 為超時時間，以 ms 為單位。成功返回實際讀寫的位元組數，失敗返回負值。

輔助函式介面

1. char *usb_strerror(void);

函式功能：根據錯誤返回值 errno，返回錯誤碼碼對應的字串。

2. void usb_set_debug(int level);

函式功能：設定 libusb 的除錯級別，libusb 支援列印除錯資訊，level 值為指定的除錯級別。

3. struct usb_device *usb_device(usb_dev_handle *dev);

函式功能：根據控制程式碼返回對應的 usb_device。

有想法或者疑問可以給我郵件或者評論，覺得有用就點贊吧~:-D