 |
libusb 1.0.24
USBデバイスにアクセスするためのクロス・プラットフォームのユーザー・ライブラリ
|
|
libusb 1.0.24
USBデバイスにアクセスするためのクロス・プラットフォームのユーザー・ライブラリ
|
以下の各機能は、各行に記述の操作を支援するように設計されています: さらに…
Typedef | |
| typedef struct libusb_device | libusb_device |
| typedef struct libusb_device_handle | libusb_device_handle |
Enum | |
| enum | libusb_speed
{ LIBUSB_SPEED_UNKNOWN = 0, LIBUSB_SPEED_LOW = 1, LIBUSB_SPEED_FULL = 2, LIBUSB_SPEED_HIGH = 3, LIBUSB_SPEED_SUPER = 4, LIBUSB_SPEED_SUPER_PLUS = 5 } |
以下に記載されている各機能は、各業に記述の操作を支援するように設計されています:
以下の説明は、実際よりも複雑に聞こえます。 次の一連の関数呼び出しは、ほとんどすべてのシナリオに適しており、リソース管理の問題を深く理解している必要はありません:
2つの重要な点:
ハンドルを使い終わったら、デバイスでの入出力に進むことができます。
libusbには、libusb_device不透明(opaque)型で表されるUSBデバイスの概念があります。デバイスは、現在または以前にシステムに接続されていたUSBデバイスを表します。デバイスへの参照を使用して、デバイスに関する特定の情報を判別できます(たとえば、デスクリプター・データを読み取ることができます)。
libusb_get_device_list()関数を使用して、現在システムに接続されているデバイスのリストを取得できます。これは、デバイス検出として知られています。
デバイスへの参照があるからといって、それが必ずしも使用可能であるとは限りません。デバイスのプラグが抜かれているか、そのようなデバイスを操作する権限がないか、別のプログラムまたはドライバーがデバイスを使用している可能性があります。
操作したいデバイスを見つけたら、libusb_open()関数を使用してデバイスをオープンするようlibusbに依頼する必要があります。成功すると、libusbはデバイス・ハンドル(libusb_device_handleポインタ)を返します。すべての "実際の" 入出力操作は、元のデバイス・ポインタではなくそのハンドルで操作します。
これらの問題を処理するために、libusbは2つの別個のアイテムを提供します:
libusb_get_device_list()関数によって提示される新しいデバイスの参照カウンターはすべて1です。libusb_ref_device() と libusb_unref_device() を使用して参照カウンターを増減できます。参照カウンターが0に達すると、デバイスは破棄されます。
上記の情報を念頭に置くと、デバイスをオープンする手順は以下のようになります:
この順番は重要です。参照解除(unreference)はデバイスを破壊する可能性があるため、オープンする前にデバイスへの参照を解除(unreference)しないでください。
便宜上、libusb_free_device_list() 関数には、リスト自体を解放する前に、オプションでリスト内のすべてのデバイスを参照解除(unreference)するパラメーターが含まれています。これは、上記のステップ3と4を組み合わせたものです。
実装の詳細として、libusb_open()は実際に問題のデバイスへの参照を追加します。 これは、デバイスがlibusb_get_device()を介してハンドルから引き続き利用できるためです。参照は、libusb_close()の処理中に削除されます。
| typedef struct libusb_device libusb_device |
システムで検出されたUSBデバイスを表す構造(structure)。 これは不透明(opaque)型であり、通常は libusb_get_device_list() からポインタが提供されます。
特定の操作はデバイスで実行できますが、入出力を実行するには、最初に libusb_open() を使用してデバイス・ハンドルを取得する必要があります。
デバイスは、libusb_ref_device() と libusb_unref_device() により参照カウンターを増減し、参照カウンターが0に達すると解放されます。libusb_get_device_list() によって提示される新しいデバイスの参照カウンターは1で、 libusb_free_device_list() はオプションでリスト内のすべてのデバイスの参照カウンターを減らすことができます。 libusb_open() は、後で libusb_close() によって破棄される別の参照を追加します。
| typedef struct libusb_device_handle libusb_device_handle |
USBデバイスのハンドルを表す構造(structure)。これは不透明(opaque)型であり、通常は libusb_open() からポインタが提供されます。
デバイス・ハンドルは、入出力およびその他の操作を実行するために使用されます。デバイス・ハンドルを使い終わったら、 libusb_close() を呼び出す必要があります。
| enum libusb_speed |
速度コード。デバイスが動作している速度を示します。
| ssize_t libusb_get_device_list | ( | libusb_context * | ctx, |
| libusb_device *** | list | ||
| ) |
現在システムに接続されているUSBデバイスのリストを返します。 これは、あなたが動作するUSBデバイスを見つけるための入り口です。
使い終わったら、すべてのデバイスの参照を解除し、 libusb_free_device_list() を使用してリストを解放する必要があります。注意: libusb_free_device_list() すべてのデバイスの参照を取り消すことができることに注意してください。 これから開こうとしているデバイスをオープンする前に参照を解除しないように注意して下さい。
この関数のこの戻り値は、結果のリスト内のデバイスの数を示します。リストはNULLで終了するため、実際には1要素大きくなります。
| ctx | 操作するコンテキスト。デフォルトのコンテキストの場合はNULL |
| list | デバイスのリストの出力場所。 後で libusb_free_device_list() を使用して解放する必要があります。 |
| void libusb_free_device_list | ( | libusb_device ** | list, |
| int | unref_devices | ||
| ) |
libusb_get_device_list() を使用して以前に検出されたデバイスのリストを解放します。unref_devicesパラメーターが0以外にセットされている場合、リスト内の各デバイスの参照カウントは1ずつ減少します。
| list | 開放したいリスト |
| unref_devices | リスト内のデバイスをunrefするかどうか(訳注:0以外ならunrefする) |
| uint8_t libusb_get_bus_number | ( | libusb_device * | dev | ) |
デバイスが接続されているバス番号を取得する。
| dev | デバイス |
| uint8_t libusb_get_port_number | ( | libusb_device * | dev | ) |
デバイスが接続されているポートの番号を取得します。OSが何かファンキーなことをしたり、USB拡張カードを活線挿抜(hot-plugging)したりしない限り、この呼び出しによって返されるポート番号は通常、物理ポートに一意に関連付けられていることが保証されます。つまり、同じ物理ポートに接続された異なるデバイスは同じポート番号を返す必要があります。
ただし、これ以外では、この呼び出しによって返されるポート番号が同じままである、またはHUB/HCDメーカーによってポートに番号が付けられた順序と一致するという保証はありません。
| dev | デバイス |
| int libusb_get_port_numbers | ( | libusb_device * | dev, |
| uint8_t * | port_numbers, | ||
| int | port_numbers_len | ||
| ) |
指定されたデバイスのルート(root)からすべてのポート番号のリストを取得する
バージョン 1.0.16 以降。LIBUSB_API_VERSION >= 0x01000102
| dev | デバイス |
| port_numbers | ポート番号達が入る配列 |
| port_numbers_len | 配列の最大長。 USB 3.0の仕様によると、深さの現在の最大制限は7です。 |
| int libusb_get_port_path | ( | libusb_context * | ctx, |
| libusb_device * | dev, | ||
| uint8_t * | port_numbers, | ||
| uint8_t | port_numbers_len | ||
| ) |
| libusb_device* libusb_get_parent | ( | libusb_device * | dev | ) |
指定されたデバイスからその親(parent)を取得します。
| dev | デバイス |
| uint8_t libusb_get_device_address | ( | libusb_device * | dev | ) |
接続されているバス上のデバイスのアドレスを取得します。
| dev | デバイス |
| int libusb_get_device_speed | ( | libusb_device * | dev | ) |
デバイスのネゴされた接続速度を取得します。
| dev | デバイス |
| int libusb_get_max_packet_size | ( | libusb_device * | dev, |
| unsigned char | endpoint | ||
| ) |
アクティブなデバイス構成の特定のエンドポイントのwMaxPacketSize値を取得するための便利な関数。
この関数は、もともとアイソクロナス転送を設定する際に役立つことを目的としていましたが、設計ミスにより、代わりにこの関数が発生しました。内容を考慮せずに、単にwMaxPacketSize値を返します。アイソクロナス転送を処理している場合は、代わりに libusb_get_max_iso_packet_size() が必要になる可能性があります。
| dev | デバイス |
| endpoint | 問い合わせのエンドポイントのアドレス |
| int libusb_get_max_iso_packet_size | ( | libusb_device * | dev, |
| unsigned char | endpoint | ||
| ) |
特定のエンドポイントが1マイクロ・フレームの期間に送受信できる最大パケット・サイズを計算します
アクティブな構成のみが検査されます。計算は、USB 2.0仕様のセクション9.6.6で説明されているように、エンドポイント・デスクリプターのwMaxPacketSizeフィールドに基づいています。
アイソクロナス・エンドポイントまたは割り込みエンドポイントで動作する場合、この関数はビット 0:10 で見つかった値に、マイクロ・フレームあたりの取引数(ビット 11:12 で決定)を掛けます。それ以外の場合、この関数はビット 0:10 にある数値を返すだけです。 USB 3.0デバイスの場合、エンドポイント・コンパニオン・デスクリプターを取得してwBytesPerIntervalを返そうとします。
この関数は、アイソクロナス転送を設定する場合に役立ちます。たとえば、転送内のすべてのアイソクロナス・パケットのlengthフィールドを設定するために、この関数からの戻り値を libusb_set_iso_packet_lengths() に渡すことができます。
v1.0.3 以降。
| dev | デバイス |
| endpoint | 問い合わせのエンドポイントのアドレス |
| libusb_device* libusb_ref_device | ( | libusb_device * | dev | ) |
デバイスの参照カウンターをインクリメントする。
| dev | 対象のデバイス |
| void libusb_unref_device | ( | libusb_device * | dev | ) |
デバイスの参照カウンターをデクリメントします。 デクリメント操作によって参照カウンターがゼロに達した場合、デバイスは破棄されます。
| dev | 参照カウンターをデクリメントしたいデバイス |
| int libusb_wrap_sys_device | ( | libusb_context * | ctx, |
| intptr_t | sys_dev, | ||
| libusb_device_handle ** | dev_handle | ||
| ) |
プラットフォーム固有のシステム・デバイス・ハンドルをラップし、基盤となるデバイスのlibusbデバイス・ハンドルを取得します。 ハンドルを使用すると、libusbを使用して問い合わせのデバイスで入出力を実行できます。
USBデバイスに直接アクセスする権限がない場合は、libusb_initの前に libusb_set_option(NULL, LIBUSB_OPTION_WEAK_AUTHORITY) を呼び出す必要があります。
Linuxでは、システム・デバイス・ハンドルは、デバイス・ノードで開かれている有効なファイル・デスクリプターである必要があります。
システム・デバイス・ハンドルは、 libusb_close() が呼び出されるまで開いたままにする必要があります。 システム・デバイス・ハンドルは、 によって閉じられません。
内部的に、この関数は一時的なデバイスを作成し、 libusb_get_device() を介して利用できるようにします。 このデバイスは、 libusb_close() 中に破棄されます。 デバイスは、 libusb_open() を介して開かないでください。
これは非ブロッキング関数です。バスを介してリクエストは送信されません。
バージョン 1.0.23以降。LIBUSB_API_VERSION >= 0x01000107
| ctx | 操作するコンテキスト。デフォルトのコンテキストの場合はNULL |
| sys_dev | プラットフォーム固有のシステム・デバイス・ハンドル |
| dev_handle | 返されたデバイス・ハンドル・ポインタの出力場所。戻りコードが0の場合にのみ入力されます。 |
| int libusb_open | ( | libusb_device * | dev, |
| libusb_device_handle ** | dev_handle | ||
| ) |
デバイスを開き、デバイス・ハンドルを取得します。ハンドルを使用すると、問い合わせのデバイスで入出力Oを実行できます。
内部的に、この関数はデバイスへの参照を追加し、 libusb_get_device() を介して使用できるようにします。 その参照は、 libusb_close() 中に削除されます。
これは非ブロッキング関数です。バスを介してリクエストは送信されません。
| dev | オープンしたいデバイス |
| dev_handle | 返されたデバイス・ハンドル・ポインタの出力場所。戻りコードが0の場合にのみ入力されます。 |
| libusb_device_handle* libusb_open_device_with_vid_pid | ( | libusb_context * | ctx, |
| uint16_t | vendor_id, | ||
| uint16_t | product_id | ||
| ) |
特定の idVendor と idProduct
の組み合わせを持つデバイスを見つけるための便利な機能。この関数は、libusbを使用してちょいと試しのアプリケーションをでっち上げる場合に使えます。これにより、
libusb_get_device_list()
を呼び出したり、そのリストを辿ったり解放したりすることを心配する必要がなくなります。
この機能には制限があるため、本番アプリケーションでの使用は想定されていません。複数のデバイスが同じIDを持っている場合、最初のだけが提供されます。
| ctx | 操作するコンテキスト。デフォルトのコンテキストの場合はNULL |
| vendor_id | 探したいidVendor値 |
| product_id | 探したいidProduct値 |
| void libusb_close | ( | libusb_device_handle * | dev_handle | ) |
デバイス・ハンドルをクローズします。アプリケーションが終了する前に、オープン中の全てのハンドルについて呼び出す必要があります。
内部的に、この関数は、指定のデバイスで libusb_open() によって追加された参照を破棄します。
これは非ブロッキング関数です。バスを介してリクエストは送信されません。
| dev_handle | クローズしたいデバイス・ハンドル |
| libusb_device* libusb_get_device | ( | libusb_device_handle * | dev_handle | ) |
デバイス・ハンドルの基になるデバイスを取得します。 この関数は、返されたデバイスの参照カウンターを変更しないため、完了時に参照を解除する必要はありません。
| dev_handle | デバイス・ハンドル |
| int libusb_get_configuration | ( | libusb_device_handle * | dev_handle, |
| int * | config | ||
| ) |
現在アクティブな構成のbConfigurationValueを決定します。
あなたはこの情報を取得するために独自の制御要求を作成することもできますが、この関数には、オペレーティング・システムのキャッシュから情報を取得できる可能性があるという利点があります(入出力は含まれません)。
OSがこの情報をキャッシュしない場合、情報を取得するために制御転送が送信されている間、この関数はブロックされます。
この関数は、デバイスが未構成の状態の場合、 config 出力パラメーターに値0を返します。
| dev_handle | デバイス・ハンドル |
| config | アクティブな構成のbConfigurationValueの出力場所(戻りコード0の場合のみ有効) |
| int libusb_set_configuration | ( | libusb_device_handle * | dev_handle, |
| int | configuration | ||
| ) |
デバイスのアクティブな構成を設定します。
オペレーティング・システムは、デバイスにアクティブな構成を設定している場合と設定していない場合があります。インターフェイスを要求して他の操作を実行する前に、正しい構成が選択されていることを確認するのはアプリケーションの責任です。
選択した構成ですでに構成されているデバイスでこの関数を呼び出すと、この関数は軽量なデバイスのリセットとして機能します。つまり、現在の構成を使用してSET_CONFIGURATION要求を発行し、ほとんどのUSB関連デバイスの状態をリセットします（altsettingをゼロにリセットすると、エンドポイントはクリアされて停止(halt)し、リセットを反転させます)。
すべてのバックエンドがユーザー空間からの構成の設定をサポートしているわけではありません。これは、戻りコードLIBUSB_ERROR_NOT_SUPPORTEDで示されます。この場合、プラットフォームがデバイス構成自体を処理していることを示唆しているため、このエラーは通常無視しても安全です。
アプリケーションがインターフェイスを要求している場合、構成を変更/リセットすることはできません。インターフェイスを要求する前に、必要な構成を設定することをお勧めします。
または、最初に libusb_release_interface()
を呼び出すこともできます。
この方法で行う場合は、devのauto_detach_kernel_driverが0であることを確認する必要があります。そうしないと、インターフェイスを解放したときにカーネル・ドライバーが再接続されます。
他のアプリケーションまたはドライバーがインターフェイスを要求している場合、構成を変更/リセットすることはできません。
構成値が-1の場合、デバイスは未構成の状態になります。 USB仕様では、構成値0が未構成を表すと規定されていますが、実際にはバグって構成0があるデバイスが存在します。
独自のSET_CONFIGURATION制御要求を作成するのではなく、常にこの関数を使用する必要があります。これは、基盤となるオペレーティング・システム側ではそのような変更がいつ発生するかを知る必要があるためです。
これはブロッキング関数です。
| dev_handle | デバイス・ハンドル |
| configuration | あなたがアクティブにたい構成のbConfigurationValue。デバイスを未構成の状態にする場合は-1を指定する。 |
| int libusb_claim_interface | ( | libusb_device_handle * | dev_handle, |
| int | interface_number | ||
| ) |
指定のデバイス・ハンドルでインターフェイスを要求します。エンドポイントのいずれかで入出力を実行する前に、使用するインターフェイスを要求する必要があります。
すでに要求されているインターフェイスを要求しようとすることは合法です。その場合、libusbは何もせずに0を返します。
devのauto_detach_kernel_driverが1に設定されている場合、カーネル・ドライバーは必要に応じて取り外され、失敗すると取り外しエラー(detach
error)が返されます。
インターフェイスの要求は、純粋に論理的な操作です。バスを介してリクエストが送信されることはありません。インターフェイス要求は、アプリケーションがインターフェイスの所有権を取得することを決まりとしている、オペレーティングシステムに指示を出すために使用されます。
これはブロッキング関数です。
| dev_handle | デバイス・ハンドル |
| interface_number | あなたが要求したいインターフェイスの bInterfaceNumber |
| int libusb_release_interface | ( | libusb_device_handle * | dev_handle, |
| int | interface_number | ||
| ) |
以前に libusb_claim_interface() で要求されたインターフェイスを解放します。デバイス・ハンドルを閉じる前に、要求されたすべてのインターフェイスを解放する必要があります。
これはブロッキング関数です。 SET_INTERFACE制御要求がデバイスに送信され、インターフェイスの状態が最初の切替設定にリセットされます。
devのauto_detach_kernel_driverが1に設定されている場合、カーネル・ドライバーは、インターフェイスを解放した後に再接続されます。
| dev_handle | デバイス・ハンドル |
| interface_number | 以前要求したインターフェイスの bInterfaceNumber |
| int libusb_set_interface_alt_setting | ( | libusb_device_handle * | dev_handle, |
| int | interface_number, | ||
| int | alternate_setting | ||
| ) |
インターフェイスの切替設定をアクティブにします。 インターフェイスは、 libusb_claim_interface() で事前に要求されている必要があります。
独自のSET_INTERFACE制御要求を作成するのではなく、常にこの関数を使用する必要があります。 これは、基盤となるオペレーティング・システムがそのような変更がいつ発生したかを知る必要があるためです。
これはブロッキング関数です。
| dev_handle | デバイス・ハンドル |
| interface_number | 以前要求したインターフェイスの bInterfaceNumber |
| alternate_setting | アクティブにしたいだいたい設定の bAlternateSetting |
| int libusb_clear_halt | ( | libusb_device_handle * | dev_handle, |
| unsigned char | endpoint | ||
| ) |
エンドポイントの停止(halt)/ストール(stall)状態をクリアします。停止(halt)ステータスのエンドポイントは、停止(halt)状態が終わるまでデータを送受信できません。
停止状態をクリアする前に、保留中の転送をすべてキャンセルする必要があります。
これはブロッキング関数です。
| dev_handle | デバイス・ハンドル |
| endpoint | 停止状態をクリアしたいエンドポイント |
| int libusb_reset_device | ( | libusb_device_handle * | dev_handle | ) |
USBポートのリセットを実行して、デバイスを再初期化します。リセットが完了した後、システムは以前の構成と切替設定の復元を試みます。
リセットが失敗した場合、デスクリプターが変更された場合、または前の状態を復元できない場合、デバイスは切断されて再接続されたように見えます。これは、デバイス・ハンドルが無効になり(クローズする必要があります)、デバイスを再検出することを意味します。 この場合、戻り値はLIBUSB_ERROR_NOT_FOUNDです。
これはブロッキング関数であり、通常は顕著な遅延が発生します。
| dev_handle | リセットしたいデバイスのハンドル |
| int libusb_kernel_driver_active | ( | libusb_device_handle * | dev_handle, |
| int | interface_number | ||
| ) |
カーネル・ドライバーがインターフェイスでアクティブかどうかを確認します。カーネル・ドライバーがアクティブな場合、インターフェイスを要求することはできず、libusbは入出力を実行できません。
この機能はWindowsでは使用できません。
| dev_handle | デバイス・ハンドル |
| interface_number | チェックしたいインターフェイス |
| int libusb_detach_kernel_driver | ( | libusb_device_handle * | dev_handle, |
| int | interface_number | ||
| ) |
インターフェイスからカーネル・ドライバを取り外します。成功すると、インターフェイスを要求して入出力を実行できるようになります。
この機能はWindowsでは使用できません。
libusb自体も特別なカーネル・ドライバーを介してデバイスと通信することに注意してください。このドライバーが既にデバイスに接続されている場合、この呼び出しはデバイスを取り外しせず、LIBUSB_ERROR_NOT_FOUNDを返します。
| dev_handle | デバイス・ハンドル |
| interface_number | ドライバーを取り外したいインターフェイス |
| int libusb_attach_kernel_driver | ( | libusb_device_handle * | dev_handle, |
| int | interface_number | ||
| ) |
以前に libusb_detach_kernel_driver() を使用して取り外したインターフェイスのカーネル・ドライバーを再取り付けします。
この機能はWindowsでは使用できません。
| dev_handle | デバイス・ハンドル |
| interface_number | ドライバーを取り付けたいインターフェイス |
| int libusb_set_auto_detach_kernel_driver | ( | libusb_device_handle * | dev_handle, |
| int | enable | ||
| ) |
libusbの自動カーネル・ドライバー取り外しを有効/無効にします。これを有効にすると、libusbは、インターフェイスを要求するときにインターフェイスス上のカーネル・ドライバーを自動的に切り離し、インターフェイスを解放するときにそれを接続します。
新しくオープンしたデバイス・ハンドルでは、カーネル・ドライバーの自動取り外しはデフォルトで無効になっています。
LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVERがないプラットフォーム(訳注:libusb_has_capability(libusb_capability.LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER)が0を返す)では、この関数はLIBUSB_ERROR_NOT_SUPPORTEDを返し、libusbはこの関数が呼び出されなかったかのように続行します。
| dev_handle | デバイス・ハンドル |
| enable | 自動カーネル・ドライバー取り外しを有効にするか無効にするか |
1.8.17