| LIBUSB(3) | FreeBSD Library Functions Manual | LIBUSB(3) |
名称
libusb — USB アクセスライブラリライブラリ
USB アクセスライブラリ (libusb, -lusb)書式
#include < libusb.h>解説
libusb ライブラリは、直接 usb デバイスを管理するためのインタフェースを含んでいます。現在の実装は、libusb API の v1.0 をサポートしています。ライブラリ初期化 / 非初期化
int libusb_init( libusb_context, **ctx) この関数は、libusb を初期化します。他の libusb ルーチンが使用される前に、プログラムの最初に呼び出されなければなりません。この関数は、成功すれば、0 を返し、失敗すれば LIBUSB_ERROR を返します。void libusb_exit( libusb_context *ctx) libusb を非初期化します。アプリケーションの終わりに呼び出されなければなりません。他の libusb ルーチンは、この関数の後に呼び出されません。
const char * libusb_strerror( int code) code 引数によって与えられるエラーの ASCII 表現を取得します。この関数は、NULL を返しません。
const char * libusb_error_name( int code) code 引数によって与えられるエラー列挙型の ASCII 表現を取得します。この関数は、NULL を返しません。
void libusb_set_debug( libusb_context *ctx, int level) デバッグレベルを level に設定します。
ssize_t libusb_get_device_list( libusb_context *ctx, libusb_device ***list) 利用可能な usb デバイスのリストで list を追加し、リスト中の各デバイスへの参照を追加します。この関数によって作成されたすべてのリストのエントリは、利用者がそれらで終了したとき、それらの参照カウンタを減少しせなければなりません、そして、リスト自体は、解放されなければなりません。この関数は、リストのデバイスの数、または LIBUSB_ERROR コードを返します。
void libusb_free_device_list( libusb_device **list, int unref_devices) libusb_get_device_list によって発見されたデバイスのリストを解放します。 unref_device が 1 に設定されているなら、リスト中のすべてのデバイスは、それらの参照カウンタを一度だけ減少された状態にします。
uint8_t libusb_get_bus_number( libusb_device *dev) デバイス dev によって含まれるバスの数を返します。
int libusb_get_port_numbers( libusb_device *dev, uint8_t *buf, uint8_t bufsize) デバイス dev のためのルートからのすべてのポート番号のリストを、サイズ bufsize のバッファ buf に格納します。
int libusb_get_port_path( libusb_context *ctx, libusb_device *dev, uint8_t *buf, uint8_t bufsize) libusb_get_port_numbers と同等の推奨されない関数。
uint8_t libusb_get_device_address( libusb_device *dev) デバイス dev によって含まれた device_address を返します。
enum libusb_speed libusb_get_device_speed( libusb_device *dev) デバイスが接続されている有線の速度を返します。詳しい情報については、LIBUSB_SPEED_XXX enums を参照してください。未知の有線の速度の場合に、LIBUSB_SPEED_UNKNOWN が返されます。
int libusb_get_max_packet_size( libusb_device *dev, unsigned char endpoint) 成功すれば、wMaxPacketSize 値を返し、終点が存在しないなら、LIBUSB_ERROR_NOT_FOUND を返し、他の失敗では、LIBUSB_ERROR_OTHERS を返します。
int libusb_get_max_iso_packet_size( libusb_device *dev, unsigned char endpoint) 成功すれば、パケット乗数を掛けたパケットサイズを返し、終点が存在しないなら、LIBUSB_ERROR_NOT_FOUND を返し、他の失敗では、LIBUSB_ERROR_OTHERS を返します。
libusb_device * libusb_ref_device( libusb_device *dev) デバイス dev の参照カウンタを増加します。
void libusb_unref_device( libusb_device *dev) デバイス dev の参照カウンタを減少します。
int libusb_open( libusb_device *dev, libusb_device_handle **devh) デバイスをオープンし、device_handle を所得します。成功すれば、0 を、メモリ割り付け問題で LIBUSB_ERROR_NO_MEM を、パーミッションの問題で LIBUSB_ERROR_ACCESS を、デバイス切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、そして、他のエラーのときに LIBUSB_ERROR コードを返します。
libusb_device_handle * libusb_open_device_with_vid_pid( libusb_context *ctx, uint16_t vid, uint16_t pid) ベンダとプロダクト ID vid と pid によってデバイスをオープンするための便利関数。エラーのときに NULL を返します。
void libusb_close( libusb_device_handle *devh) デバイスハンドルをクローズします。
libusb_device * libusb_get_device( libusb_device_handle *devh) devh に含まれるデバイスを取得する。エラーのときに NULL を返します。
int libusb_get_configuration( libusb_device_handle *devh, int *config) 現在の設定の値を返します。成功すれば、0 を、デバイス切断されているなら、LIBUSB_ERROR_NO_DEVICE を、エラーのときに、LIBUSB_ERROR コードを返します。
int libusb_set_configuration( libusb_device_handle *devh, int config) devh に含まれるデバイスのための config にアクティブな設定を設定します。この関数は、成功すれば、0 を、要求された設定が存在していなければ、 LIBUSB_ERROR_NOT_FOUND を、インタフェースが現在要求されているなら、 LIBUSB_ERROR_BUSY を、デバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_claim_interface( libusb_device_handle *devh, int interface_number) 与えられた libusb_handle devh のインタフェースを要求します。これは、非ブロッキング関数です。成功すれば、0 を、要求されたインタフェースが存在していないなら、 LIBUSB_ERROR_NOT_FOUND を、プログラムまたはドライバがインタフェースを要求するなら、LIBUSB_ERROR_BUSY を、デバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_release_interface( libusb_device_handle *devh, int interface_number) この関数は、インタフェースを解放します。デバイスで要求されたすべてのインタフェースは、デバイスをクローズする前に、解放されければなりません。成功すれば、0 を、インタフェースが要求されないなら、 LIBUSB_ERROR_NOT_FOUND を、デバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_set_interface_alt_setting( libusb_device_handle *dev, int interface_number, int alternate_setting) インタフェースのため代替の設定をアクティブにします。成功すれば、0 を、インタフェースが要求されないか、または要求された設定が存在しないなら、LIBUSB_ERROR_NOT_FOUND を、デバイスが切断されているなら、LIBUSB_ERROR_NO_DEVICE を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_clear_halt( libusb_device_handle *devh, unsigned char endpoint) 終点のための halt/stall をクリアする。成功すれば、0 を、終点が存在しないなら、LIBUSB_ERROR_NOT_FOUND を、デバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_reset_device( libusb_device_handle *devh) usb デバイスのための USB ポートリセットを実行します。成功すれば、0 を、再列挙が要求されるか、または、デバイスが切断されているなら、 LIBUSB_ERROR_NOT_FOUND を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_check_connected( libusb_device_handle *devh) USB デバイスがまだ接続されているかどうかテストします。成功すれば、0 を、切断されているなら、LIBUSB_ERROR_NO_DEVICE を、そして失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_kernel_driver_active( libusb_device_handle *devh, int interface) ドライバがインタフェースでアクティブであるかどうか決定する。カーネルドライバがアクティブでないなら、0 を、カーネルドライバがアクティブであるなら、1 を、デバイスが切断されているなら、LIBUSB_ERROR_NO_DEVICE を、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_get_driver( libusb_device_handle *devh, int interface, char *name, int namelen) または int libusb_get_driver_np( libusb_device_handle *devh, int interface, char *name, int namelen) 与えられた device と interface にアタッチされたドライバの名前を長さ namelen のバッファ name にコピーします。成功すれば、0 を、カーネルドライバが与えられたインタフェースにアタッチされていないなら、 LIBUSB_ERROR_NOT_FOUND を、そしてインタフェースが存在していないなら、LIBUSB_ERROR_INVALID_PARAM を返します。この関数は、移植性がありません。 name によって指されたバッファは、成功して終了したときのみ 0 です。
int libusb_detach_kernel_driver( libusb_device_handle *devh, int interface) または int libusb_detach_kernel_driver_np( libusb_device_handle *devh, int interface) インタフェースからカーネルドライバをデタッチします。これは、カーネルドライバによって既に必要とされるインタフェースを要求するために必要です。成功すれば、0 を、カーネルドライバがアクティブでなかったなら、 LIBUSB_ERROR_NOT_FOUND を、インタフェースが存在していないなら、LIBUSB_ERROR_INVALID_PARAM を、デバイスが接続されていなかったなら、LIBUSB_ERROR_NO_DEVICE を、そして失敗すれば、LIBUSB_ERROR コードを返します。この関数は、移植性がありません。
int libusb_attach_kernel_driver( libusb_device_handle *devh, int interface) 以前にデタッチされたインタフェースカーネルドライバを再アタッチします。成功すれば、0 を、インタフェースが存在していないなら、 LIBUSB_ERROR_INVALID_PARAM を、デバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、インタフェースがプログラムまたはドライバによって要求されるので、ドライバをアタッチできないなら、 LIBUSB_ERROR_BUSY を、失敗すれば、LIBUSB_ERROR コードを返します。
USB 記述子
int libusb_get_device_descriptor( libusb_device *dev, libusb_device_descriptor *desc) デバイス dev のための USB デバイス記述子を取得する。これは、非ブロッキング関数です。成功すれば、0 を、失敗すれば、LIBUSB_ERROR コードを返します。int libusb_get_active_config_descriptor( libusb_device *dev, struct libusb_config_descriptor **config) アクティブな設定のための USB 設定記述子を取得する。成功すれば、0 を、デバイスが設定されない状態であるなら、 LIBUSB_ERROR_NOT_FOUND を、エラーのときに LIBUSB_ERROR コードを返します。
int libusb_get_config_descriptor( libusb_device *dev, uint8_t config_index, libusb_config_descriptor **config) インデックス idx に基づく USB 設定記述子を取得する。成功すれば、0 を、設定が存在していないなら、 LIBUSB_ERROR_NOT_FOUND を、エラーのときに LIBUSB_ERROR コードを返します。
int libusb_get_config_descriptor_by_value( libusb_device *dev, uint8 bConfigurationValue, libusb_config_descriptor **config) 特有の bConfigurationValue で USB 設定記述子を取得する。これは、デバイスを通して要求を送信しない非ブロッキング関数です。成功すれば、0 を、設定が存在していないなら、LIBUSB_ERROR_NOT_FOUND を、失敗すれば、LIBUSB_ERROR コードを返します。
void libusb_free_config_descriptor( libusb_config_descriptor *config) 設定記述子を解放する。
int libusb_get_string_descriptor( libusb_device_handle *devh, uint8_t desc_idx, uint16_t langid, unsigned char *data, int length) 生の形式での文字列の記述子を検索します。成功すれば、実際に転送されたバイトの数を返し、失敗すれば、負の LIBUSB_ERROR コードの返します。
int libusb_get_string_descriptor_ascii( libusb_device_handle *devh, uint8_t desc_idx, unsigned char *data, int length) C スタイル ASCII の文字列記述子を検索する。成功すれば、結果の ASCII 文字列に正のバイトの数を返し、失敗すれば、 LIBUSB_ERROR コードを返します。
int libusb_parse_ss_endpoint_comp( const void *buf, int len, libusb_ss_endpoint_companion_descriptor **ep_comp) この関数は、 buf によって指され、 len の長さがある、ホストのエンディアンの形式で USB 3.0 終点コンパニオン記述子を解析します。一般的に、これらの引数は、終点記述子の extra と extra_length のフィールドです。成功すれば、結果の記述子へのポインタは、 ep_comp によって与えられる場所に格納されます。成功すれば、0 を返し、失敗すれば、LIBUSB_ERROR コードを返します。成功すれば、解析された USB 3.0 終点コンパニオン記述子は、 libusb_free_ss_endpoint_comp 関数を使用して解放されなければなりません。
void libusb_free_ss_endpoint_comp( libusb_ss_endpoint_companion_descriptor *ep_comp) この関数は、NULL セーフで、解析された USB 3.0 終点コンパニオン記述子を解放します。
int libusb_parse_bos_descriptor( const void *buf, int len, libusb_bos_descriptor **bos) この関数は、バイナリオブジェクトストア (Binary Object Store)、BOS を buf によって指され、 len の長さがある、ホストのエンディアンの形式に解析します。成功すれば、結果の記述子へのポインタは、 bos によって与えられる場所に格納されます。成功すれば、0 を返し、失敗すれば、LIBUSB_ERROR コードを返します。成功すれば、解析された BOS 記述子は、 libusb_free_bos_descriptor 関数を使用して解放されなければなりません。
void libusb_free_bos_descriptor( libusb_bos_descriptor *bos) この関数は、NULL セーフで、解析された BOS 記述子を解放します。
USB 非同期 I/O
struct libusb_transfer * libusb_alloc_transfer( int iso_packets) iso_packets によって指定されるアイソクロナス (isochronous) パケット記述子に比例して転送を割り付けます。エラーのときに NULL を返します。void libusb_free_transfer( struct libusb_transfer *tr) 転送を解放します。
int libusb_submit_transfer( struct libusb_transfer *tr) この関数は、転送を提出して、直ちに、返ります。成功すれば、0 を、デバイスが切断されているなら、LIBUSB_ERROR_NO_DEVICE を、他の失敗のときに、LIBUSB_ERROR コードを返します。
int libusb_cancel_transfer( struct libusb_transfer *tr) この機関数は、転送を非同期にキャンセルします。成功すれば、0 を、失敗すれば、LIBUSB_ERROR コードを返します。
USB 同期 I/O
int libusb_control_transfer( libusb_device_handle *devh, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout) USB 制御転送を実行する。 0 から wLength までの範囲で、成功すれば、実際に転送されたバイト数を返します。エラー時には、libusb エラーコードが返されます、例えば、転送タイムアウトしたなら、LIBUSB_ERROR_TIMEOUT を、制御要求がサポートされていないなら、LIBUSB_ERROR_PIPE を、デバイスが切断されているなら、LIBUSB_ERROR_NO_DEVICE を、または、他の失敗のときに、別の LIBUSB_ERROR コードを返します。 LIBUSB_ERROR コードは、すべて負です。int libusb_bulk_transfer( struct libusb_device_handle *devh, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout) USB バルク転送を実行する。 0 のタイムアウト値は、タイムアウトを意味しません。タイムアウト値は、ミリ秒単位で与えられます。成功すれば、0 を、転送タイムアウトであるなら、LIBUSB_ERROR_TIMEOUT を、制御要求がサポートされていないなら、 LIBUSB_ERROR_PIPE をデバイスがより多くのデータを提供するなら、 LIBUSB_ERROR_OVERFLOW をデバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、他の失敗のときに、LIBUSB_ERROR コードを返します。
int libusb_interrupt_transfer( struct libusb_device_handle *devh, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout) USB 割り込み転送を実行する。 0 のタイムアウト値は、タイムアウトを意味しません。タイムアウト値は、ミリ秒単位で与えられます。成功すれば、0 を、転送タイムアウトであるなら、LIBUSB_ERROR_TIMEOUT を、制御要求がサポートされていないなら、LIBUSB_ERROR_PIPE をデバイスがより多くのデータを提供するなら、LIBUSB_ERROR_OVERFLOW をデバイスが切断されているなら、 LIBUSB_ERROR_NO_DEVICE を、他の失敗のときに、LIBUSB_ERROR コードを返します。
USB イベント
int libusb_try_lock_events( libusb_context *ctx) イベント取り扱いロックを獲得するように試みる。ロックが取得されたなら、0 を返し、そうでなければ、1 を返します。void libusb_lock_events( libusb_context *ctx) イベント取り扱いロックを獲得する。この関数は、ブロッキングです。
void libusb_unlock_events( libusb_context *ctx) イベント取り扱いロックを解放する。これは、 libusb_wait_for_event() でブロックされた任意のスレッドを起こします。
int libusb_event_handling_ok( libusb_context *ctx) イベント取り扱いを行うためにこのスレッドに対してまだ OK かどうか判断する。イベント取り扱いが始まるか、または続くことができるなら、1 を返します。このスレッドがイベントロックをあきらめなければならないなら、0 を返します。
int libusb_event_handler_active( libusb_context *ctx) アクティブなスレッドがイベントを取り扱っているかどうか判断します。スレッド処理イベントがあるから、1 を、現在処理イベントがなければ、0 を返します。
void libusb_lock_event_waiters( libusb_context *ctx) event_waiters ロックを獲得する。このロックは、イベントが終了しているとき、利用者が承知したい状況で取得されるように設計されていますが、ある他のスレッドは、イベント処理であるので、 libusb_handle_events() の呼び出しは、許可されていません。
void libusb_unlock_event_waiters( libusb_context *ctx) event_waiters ロックを解放する。
int libusb_wait_for_event( libusb_context *ctx, struct timeval *tv) イベントの終了のシグナルを発生するために別のスレッドを待ちます。イベントウェータ (waiter) ロックを保持して呼び出されなければなりません、 libusb_lock_event_waiters() 参照。これは、タイムアウトの期限が切れるか、転送が完了するか、スレッドが、libusb_unlock_events() を通してイベント取り扱いロックを解放するまで、ブロックします。転送が完了するか、または別のスレッドがイベント取り扱い停止した後、0 を返し、タイムアウトの期限が切れたなら、1 を返します。
int libusb_handle_events_timeout( libusb_context *ctx, struct timeval *tv) タイムアウトの期限が切れたかどうかチェックし、活性のためにファイル記述子のセットをチェックすることによって、任意の保留中 (pending) のイベントを取り扱います。成功すれば、0 を返し、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_handle_events( libusb_context *ctx) センシブル (sensible) タイムアウトでブロッキングモードの保留中のイベントを取り扱います。成功すれば、0 を返し、失敗すれば、LIBUSB_ERROR コードを返します。
int libusb_handle_events_locked( libusb_context *ctx, struct timeval *tv) 別のスレッドが既にそれを行っているかどうかチェックすることなしに、ファイル記述子をポーリングすることによって保留中のイベントを取り扱います。イベントロックが保持されている状態で、呼び出されなければなりません。
int libusb_get_next_timeout( libusb_context *ctx, struct timeval *tv) libusb が取り扱う必要がある次の内部のタイムアウトを決定します。保留中のタイムアウトがなければ、0 を、タイムアウトが返されたなら、1 を、失敗すれば、LIBUSB_ERROR コードを返します。
void libusb_set_pollfd_notifiers( libusb_context *ctx, libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb remove_cb, void *user_data) ファイル記述子追加/削除のための通知関数を登録します。これらの関数は、libusb がイベントソースとして使用しているすべての新しいか、または削除されるファイル記述子のために呼び出されます。
const struct libusb_pollfd ** libusb_get_pollfds( libusb_context *ctx) libusb イベントソースとして、利用者のメインループによって、ポーリングされるべき、ファイル記述子のリストを検索します。成功すれば、NULL で終了するリストを返し、失敗すれば、NULL を返します。
LIBUSB バージョン 0.1 互換性
また、ライブラリは、LibUSB バージョン 0.1.12 に準拠しています。usb_open() usb_close() usb_get_string() usb_get_string_simple() usb_get_descriptor_by_endpoint() usb_get_descriptor() usb_parse_descriptor() usb_parse_configuration() usb_destroy_configuration() usb_fetch_and_parse_descriptors() usb_bulk_write() usb_bulk_read() usb_interrupt_write() usb_interrupt_read() usb_control_msg() usb_set_configuration() usb_claim_interface() usb_release_interface() usb_set_altinterface() usb_resetep() usb_clear_halt() usb_reset() usb_strerror() usb_init() usb_set_debug() usb_find_busses() usb_find_devices() usb_device() usb_get_busses() usb_check_connected() usb_get_driver_np() usb_detach_kernel_driver_np()
歴史
libusb サポートは、 FreeBSD 8.0 ではじめて登場しました。| June 7, 2013 | FreeBSD |