はじめに

libusbは、ユーザー空間からUSBデバイスと通信できるようにするオープン・ソース・ライブラリです。詳細については、 libusb homepage を参照してください。

この文書は、独自のソフトウェアからUSB周辺機器と通信したいアプリケーション開発者を対象としています。この文書を読んだ後で、フィードバックや質問を libusb-devel mailing list メーリングリストに投げる事もできます。

この文書は、ソフトウェアの観点(デスクリプター、構成、インターフェイス、エンドポイント、制御/バルク/割り込み/アイソクロナス転送など)からUSBデバイスを操作する方法に関する知識を前提としています。詳細については、無料でダウンロードできる USB 3.0 Specification を参照してください。 Webを検索すると、冗長性の低い説明を見つけることもできます。

アプリケーション・プログラミング・インターフェイス (API)

libusb関数の完全なリストについては、アプリケーション・プログラミング・インターフェイスページを参照してください。

ライブラリの機能

全ての転送型をサポートしています(制御/バルク/割り込み/アイソクロナス)
2つの転送インターフェイス:
1. 同期(synchronous)(シンプル)
2. 非同期(asynchronous)(より複雑だけど、より強力)
スレッド・セーフ(けれども、通常あなたは非同期インターフェイスをスレッド化する必要がありません)
無駄のない軽量API
libusb-compat-0.1変換レイヤーを介してlibusb-0.1と互換性があります
(幾つかのプラットフォームでは)活線挿抜(hotplug)をサポート。デバイスの活線挿抜イベント通知を参照してください。

ここから始めます

API文書を読み始めるには、libusbの機能のさまざまなカテゴリにリンクしているモジュール・ページから始めます。

あなたが行う必要がある決定の１つは、同期または非同期のどちらのデータ転送インターフェイスを使用するかどうかです。同期・非同期のデバイス入出力の文書は、この話題に関する洞察を提供します。

いくつかのサンプル・プログラムは、libusbソース・ディストリビューションの "examples" サブ・ディレクトリにあります。 libusbホームページには、libusbを使用する実際のプロジェクト例のリストが含まれています。

エラー処理

libusb関数は通常、成功した場合は0を返し、失敗した場合は負のエラー・コードを返します。これらの負のエラー・コードは、その他の文書ページにリストされているLIBUSB_ERROR定数に関連しています。

デバッグ・メッセージ・ロギング

libusbは、すべてのロギングにstderrを使用します。デフォルトでは、ロギングはNONEに設定されています。これは、出力が生成されないことを意味します。ただし、ライブラリがロギングを無効にしてコンパイルされていない限り、libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level)へのアプリケーション呼び出し、またはアプリケーション外での環境変数LIBUSB_DEBUGの設定により、ロギングが生成される可能性があります。したがって、アプリケーションはstderrを閉じるのではなく、出力が望ましくない場合はnullデバイスに転送する必要があります。

libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level)関数を使用して、特定のメッセージのログを有効にすることができます。標準構成では、libusbは実際には多くのログを記録しないため、この関数を使用してすべてのエラー/警告/情報メッセージを有効にすることをお勧めします。ソフトウェアの問題をデバッグするのに役立ちます。

ログに記録されたメッセージは構造化されていません。ログに記録されるメッセージと、libusb関数からの成功または失敗の戻りコードとの間に1対1の対応はありません。メッセージには形式がないため、メッセージをキャプチャまたは解析しようとしないでください。それらはローカライズされておらず、今後もローカライズされません。これらのメッセージは、アプリケーション・ユーザーに渡されることを意図したものではありません。代わりに、libusb関数から返されたエラーコードを解釈し、ユーザーに適切な通知を提供する必要があります。メッセージはプログラマーとしてのあなたを助けるために単にそこにあります、そしてあなたがlibusb関数から奇妙なエラーコードを受け取っているために混乱しているなら、メッセージ・ロギングを有効にすることはあなたに適切な説明を与えるかもしれません。

LIBUSB_DEBUG環境変数を使用して、実行時にメッセージ・ログを有効にすることができます。この環境変数は、libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level)パラメーターと同じように解釈されるログ・レベル番号に設定する必要があります。この環境変数が設定されている場合、メッセージ・ログの詳細レベルは固定され、libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level)は事実上何もしません。

libusbは、ロギング関数なしでコンパイルでき、組み込みシステムで利用できます。この場合、libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level)およびLIBUSB_DEBUG環境変数は効果がありません。

libusbは、常に詳細なデバッグ・メッセージを使用するようコンパイルすることもできます。ライブラリがこのようにコンパイルされると、すべての詳細度のすべてのメッセージが常にログに記録されます。libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level)およびLIBUSB_DEBUG環境変数は効果がありません。

その他注意点

libusbには欠陥があります。警告ページはこれらを文書化しようとします。