ライブラリの利用準備と後片付け

このページでは、libusbを利用準備(initialize)および後片付け(deinitialize)する方法について詳しく説明します。 libusb機能を使用する前に利用準備を実行する必要があります。同様に、後片付け後にlibusb関数を呼び出さないでください。 詳細説明へ

データ構造体
struct	libusb_version

Typedef
typedef struct libusb_context	libusb_context
typedef void(*	libusb_log_cb) (libusb_context *ctx, enum libusb_log_level level, const char *str)

列挙型
enum	libusb_log_level {   LIBUSB_LOG_LEVEL_NONE = 0, LIBUSB_LOG_LEVEL_ERROR = 1, LIBUSB_LOG_LEVEL_WARNING = 2, LIBUSB_LOG_LEVEL_INFO = 3,   LIBUSB_LOG_LEVEL_DEBUG = 4 }
enum	libusb_log_cb_mode { LIBUSB_LOG_CB_GLOBAL = (1 << 0), LIBUSB_LOG_CB_CONTEXT = (1 << 1) }
enum	libusb_option { LIBUSB_OPTION_LOG_LEVEL = 0, LIBUSB_OPTION_USE_USBDK = 1, LIBUSB_OPTION_WEAK_AUTHORITY = 2, LIBUSB_OPTION_MAX = 3 }

関数
void	libusb_set_debug (libusb_context *ctx, int level)
void	libusb_set_log_cb (libusb_context *ctx, libusb_log_cb cb, int mode)
int	libusb_set_option (libusb_context *ctx, enum libusb_option option,...)
int	libusb_init (libusb_context **ctx)
void	libusb_exit (libusb_context *ctx)

詳細説明

このページでは、libusbを利用準備(initialize)および後片付け(deinitialize)する方法について詳しく説明します。 libusb機能を使用する前に利用準備(initialization)を実行する必要があります。同様に、後片付け(deinitialization)後にlibusb関数を呼び出さないでください。

Typedef解説

libusb_context

typedef struct libusb_context libusb_context

libusbセッションを表す構造体。 個々の独立したlibusbセッションの概念により、プログラムで2つのライブラリを使用する(または2つのモジュールを動的にロードする)ことができます。これらは両方とも独立してlibusbを使用します。これにより、個々のlibusbユーザー間の干渉が防止されます。たとえば libusb_set_option() はライブラリの他のユーザーに影響を与えず、 libusb_exit() は他のユーザーがまだ使用しているリソースを破壊しません。

セッションは libusb_init() によって作成され、 libusb_exit() によって破棄されます。 アプリケーションに単一のlibusbユーザー(つまり、あなただけ)のみが含まれることが保証されている場合は、コンテキストについて心配する必要はありません。あなたはコンテキストが必要なすべての関数呼び出しでNULLを渡して下さい。デフォルトのコンテキストが使用されます。

詳細については、 コンテキスト を参照してください。

libusb_log_cb

typedef void( * libusb_log_cb) (libusb_context *ctx, enum libusb_log_level level, const char *str)

ログ・メッセージを処理するためのコールバック関数。

パラメーター

ctx	ログ・メッセージに関連するコンテキスト。NULLの場合はグローバル・ログ・メッセージ
level	ログ・レベル。 libusb_log_level に説明があります。
str	ログ・メッセージ

バージョン 1.0.23 以降。 LIBUSB_API_VERSION >= 0x01000107

以下もご覧下さい

libusb_set_log_cb()

列挙型解説

libusb_log_level

enum libusb_log_level

ログ・レベル。

列挙型
LIBUSB_LOG_LEVEL_NONE	(0) : ライブラリからメッセージが出されることはありません(デフォルト)
LIBUSB_LOG_LEVEL_ERROR	(1) : (ERROR)エラーメッセージを出します
LIBUSB_LOG_LEVEL_WARNING	(2) : 警告(WARNING)とエラー(ERROR)メッセージを出します
LIBUSB_LOG_LEVEL_INFO	(3) : 通知(INFO)と警告(WARNING)とエラー(ERROR)メッセージを出します。
LIBUSB_LOG_LEVEL_DEBUG	(4) : 全てのメッセージを出します

libusb_log_cb_mode

enum libusb_log_cb_mode

ログ・コールバック・モード。

バージョン 1.0.23 以降。 LIBUSB_API_VERSION >= 0x01000107

以下もご覧下さい

libusb_set_log_cb()

列挙型
LIBUSB_LOG_CB_GLOBAL	すべてのログ・メッセージを処理するコールバック関数。
LIBUSB_LOG_CB_CONTEXT	コンテキスト関連のログ・メッセージを処理するコールバック関数。

libusb_option

enum libusb_option

libusb_set_option() で使用可能なオプション値。

列挙型
LIBUSB_OPTION_LOG_LEVEL	ログ・メッセージを冗舌(verbosity)に設定する。 デフォルトのレベルはLIBUSB_LOG_LEVEL_NONEです。これは、メッセージが出力されないことを意味します。メッセージの詳細レベルを上げることを選択した場合は、アプリケーションでstderrファイル・デスクリプターを閉じないようにしてください。 レベルLIBUSB_LOG_LEVEL_WARNINGを使用することをお勧めします。libusbはメッセージのログ記録を控えめにしており、ほとんどの場合、エラー状態やその他の異常を説明するメッセージのみをログに記録します。これは、ソフトウェアのデバッグに役立ちます。 libusbの使用準備(initialize)時にLIBUSB_DEBUG環境変数が設定されている場合、この関数は何も実行しません。メッセージの詳細度は環境変数の値に固定されます。 libusbがメッセージ・ロギングなしでコンパイルされた場合、この関数は何もしません。あなたがメッセージを受け取ることはありません。 libusbが詳細なデバッグ・メッセージ・ロギングを使用してコンパイルされている場合、この関数は何もしません。常にすべてのレベルのメッセージを出します。
LIBUSB_OPTION_USE_USBDK	可能な場合は、指定のコンテキストにUsbDkバックエンドを使用します。 このオプションは、 libusb_init() を呼び出した直後に設定する必要があります。そうしないと、不特定の動作が発生する可能性があります。 Windowsでのみ有効です。
LIBUSB_OPTION_WEAK_AUTHORITY	libusbの権限が弱い事を示すフラグ。 このオプションを設定すると、libusbは libusb_init() 内でのデバイスのスキャンをスキップします。 このオプションは、 libusb_init() を呼び出す前に設定する必要があります。そうしないと、 libusb_init() が失敗する可能性があります。 このオプションは通常Androidで必要であり、 libusb_wrap_sys_device() と一緒に使用されます。 Linuxでのみ有効です。

関数解説

libusb_set_debug()

void libusb_set_debug	(	libusb_context *	ctx,
		int	level
	)

非推奨:

代わりに、 LIBUSB_OPTION_LOG_LEVEL オプションを使用して libusb_set_option() を使用してください。

libusb_set_log_cb()

void libusb_set_log_cb	(	libusb_context *	ctx,
		libusb_log_cb	cb,
		int	mode
	)

ログ・ハンドラーをセットする。

libusbは、ログ・メッセージを提供されたコールバック関数にリダイレクトします。 libusbは、コンテキストごとのリダイレクトとグローバル・ログ・メッセージをサポートします。コンテキストに送信されたログ・メッセージは、グローバル・ログ・ハンドラーにも送信されます。

libusbがメッセージ・ロギングなしでコンパイルされているか、USE_SYSTEM_LOGGING_FACILITYが定義されている場合、グローバル・コールバック関数は呼び出されません。ENABLE_DEBUG_LOGGINGが定義されている場合、コンテキストごとのコールバック関数は呼び出されません。

バージョン 1.0.23 以降。 LIBUSB_API_VERSION >= 0x01000107

パラメーター

ctx	ログ・ハンドラーを割り当てるコンテキスト、またはデフォルト・コンテキストの場合はNULL。 LIBUSB_LOG_CB_GLOBALモードのみが要求された場合、パラメーターは無視されます。
cb	コールバック関数へのポインタ。ログ・メッセージのリダイレクトを停止する場合はNULL
mode	コールバック関数操作のモード。 1つのコールバック関数に対して複数のモードを選択できます。 libusb_log_cb_mode に説明があります。

以下もご覧下さい

libusb_log_cb, libusb_log_cb_mode

libusb_set_option()

int libusb_set_option	(	libusb_context *	ctx,
		enum libusb_option	option,
			...
	)

ライブラリにオプションを設定します。

この関数を使用して、ライブラリ内の特定のオプションを構成します。

一部のオプションでは、1つ以上の引数を指定する必要があります。特定の要件については、各オプションの説明を参照してください。

バージョン 1.0.22 以降。 LIBUSB_API_VERSION >= 0x01000106

パラメーター

ctx	操作したいコンテキスト
option	どのオプションを設定するか
...	指定のオプションに必要な引数

戻り値

LIBUSB_SUCCESS ならば成功

LIBUSB_ERROR_INVALID_PARAM オプションまたは引数が無効な場合

LIBUSB_ERROR_NOT_SUPPORTED オプションが有効であるがこのプラットフォームでサポートされていない場合

LIBUSB_ERROR_NOT_FOUND : LIBUSB_OPTION_USE_USBDKがこのプラットフォームで有効であるが、UsbDkが使用できない場合

libusb_init()

int libusb_init

(

libusb_context **

ctx

)

libusbの利用準備(initialize)をします。 この関数は、他のlibusb関数を呼び出す前に呼び出す必要があります。

コンテキスト・ポインタの出力場所を指定しない場合、デフォルトのコンテキストが作成されます。 デフォルトのコンテキストがすでに存在する場合、それは再利用されます(そして、何も利用準備(initialize)/再利用準備(reinitialize)しません)。

パラメーター

ctx	コンテキスト・ポインタのオプションの出力場所。 戻り値が0の時だけ有効です。

戻り値

0 ならば成功。LIBUSB_ERROR ならば失敗

以下もご覧下さい

libusb_contexts

libusb_exit()

void libusb_exit

(

libusb_context *

ctx

)

libusbを後片付け(deinitialize)します。開いているすべてのデバイスをクローズした後、アプリケーションが終了する前に呼び出す必要があります。

パラメーター

ctx	後片付け(deinitialize)するコンテキスト、またはデフォルトのコンテキストの場合はNULL