デバイス活線挿抜(hotplug)イベント通知

このページでは、libusb活線挿抜(hotplug)インターフェイスの使用方法について詳しく説明します(利用可能な場合)。 さらに…

マクロ
#define	LIBUSB_HOTPLUG_NO_FLAGS   0
#define	LIBUSB_HOTPLUG_MATCH_ANY   -1

Typedef
typedef int	libusb_hotplug_callback_handle
typedef int(*	libusb_hotplug_callback_fn) (libusb_context *ctx, libusb_device *device, libusb_hotplug_event event, void *user_data)

列挙型
enum	libusb_hotplug_event { LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = (1 << 0), LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT = (1 << 1) }
enum	libusb_hotplug_flag { LIBUSB_HOTPLUG_ENUMERATE = (1 << 0) }

関数
int	libusb_hotplug_register_callback (libusb_context *ctx, int events, int flags, int vendor_id, int product_id, int dev_class, libusb_hotplug_callback_fn cb_fn, void *user_data, libusb_hotplug_callback_handle *callback_handle)
void	libusb_hotplug_deregister_callback (libusb_context *ctx, libusb_hotplug_callback_handle callback_handle)
void *	libusb_hotplug_get_user_data (libusb_context *ctx, libusb_hotplug_callback_handle callback_handle)

詳細説明

このページでは、libusb活線挿抜(hotplug)インターフェイスの使用方法について詳しく説明します(利用可能な場合)。

注意: 現在、すべてのプラットフォームがホットプラグ通知を実装しているわけではなく、最初に、パラメーター LIBUSB_CAP_HAS_HOTPLUG を指定して libusb_has_capability() を呼び出し、活線挿抜(hotplug)サポートが利用可能であることを確認する必要があることに注意してください。

マクロ定義解説

LIBUSB_HOTPLUG_NO_FLAGS

#define LIBUSB_HOTPLUG_NO_FLAGS   0

フラグを使用しない場合の便利なマクロ

LIBUSB_HOTPLUG_MATCH_ANY

#define LIBUSB_HOTPLUG_MATCH_ANY   -1

活線挿抜イベントのワイルド・カード・マッチング

Typedef解説

libusb_hotplug_callback_handle

typedef int libusb_hotplug_callback_handle

コールバック・ハンドル。

コールバック・ハンドルは libusb_hotplug_register_callback() によって生成され、コールバックの登録を解除するために使用できます。 コールバック・ハンドルはlibusb_contextごとに一意であり、すでに登録解除されているコールバックで libusb_hotplug_deregister_callback() を呼び出しても安全です。

バージョン 1.0.16 以降。 LIBUSB_API_VERSION >= 0x01000102

詳細については デバイス活線挿抜イベント通知 を参照してください。

libusb_hotplug_callback_fn

typedef int( * libusb_hotplug_callback_fn) (libusb_context *ctx, libusb_device *device, libusb_hotplug_event event, void *user_data)

活線挿抜コールバック関数タイプ。活線挿抜イベント通知を要求するときは、このタイプのコールバック関数へのポインタを渡します。

このコールバックは内部イベント・スレッドによって呼び出される可能性があるため、コールバックは戻る前に最小限の処理を行うことをお勧めします。

libusbは、一致するデバイスで一致するイベントが発生したときに、後でこの関数を呼び出します。 詳細については デバイス活線挿抜イベント通知 を参照してください。

コールバック関数内からは libusb_hotplug_register_callback() または libusb_hotplug_deregister_callback() のいずれかを呼び出しても安全です。

バージョン 1.0.16 以降。 LIBUSB_API_VERSION >= 0x01000102

パラメーター

ctx	この通知のコンテキスト
device	このイベントが発生したlibusb_device
event	発生したイベント
user_data	このコールバックが登録されたときに提供されたユーザー・データ

戻り値

このコールバックがイベントの処理を終了したかどうかをブール値で示します。 1を返すと、このコールバックの登録が解除されます

列挙型解説

libusb_hotplug_event

enum libusb_hotplug_event

バージョン 1.0.16 以降。 LIBUSB_API_VERSION >= 0x01000102

活線挿抜イベント

列挙型
LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED	デバイスが接続され、使用できるようになりました。
LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT	デバイスが外されて使用できなくなりました。 切断されたデバイスに関連付けられているハンドルでlibusb_closeを呼び出すのは、ユーザーの責任です。 外されたデバイスでlibusb_get_device_descriptorを呼び出しても安全です

libusb_hotplug_flag

enum libusb_hotplug_flag

バージョン 1.0.16 以降。 LIBUSB_API_VERSION >= 0x01000102

活線挿抜フラグ

列挙型
LIBUSB_HOTPLUG_ENUMERATE	コールバックを準備し、現在取り付けられているすべての一致するデバイスに対してコールバックを起動します。

関数解説

libusb_hotplug_register_callback()

int libusb_hotplug_register_callback	(	libusb_context *	ctx,
		int	events,
		int	flags,
		int	vendor_id,
		int	product_id,
		int	dev_class,
		libusb_hotplug_callback_fn	cb_fn,
		void *	user_data,
		libusb_hotplug_callback_handle *	callback_handle
	)

活線挿抜コールバック関数を登録する

libusb_contextにコールバックを登録します。 一致するデバイスで一致するイベントが発生すると、コールバックが発生します。 コールバックは、libusb_hotplug_deregister_callback() で登録解除されるか、提供されたコールバックが1を返し、イベントの処理が終了したことを示すまで生きたままです。

LIBUSB_HOTPLUG_ENUMERATE が渡されると、マシンにすでに接続されているすべてのデバイスに対して、 LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED を使用してコールバックが呼び出されます。libusbは、 libusb_handle_events() から活線挿抜コールバックを呼び出している間、別のスレッドから内部デバイス・リストを変更します。そのため、活線挿抜コールバックをディスパッチする必要があるときに、デバイスが内部デバイスリストにすでに存在するか、内部デバイスリストから削除される可能性がることに注意して下さい。これは、 LIBUSB_HOTPLUG_ENUMERATE を使用する場合、同じデバイスへの訪問に対してコールバックが2回呼び出される可能性があることを意味します。1回は libusb_hotplug_register_callback() から、もう1回は libusb_handle_events() からです。そしてまた、コールバックが呼び出されて、訪問した呼び出しが行われなかったデバイスを削除する場合があります。

バージョン 1.0.16 以降。 LIBUSB_API_VERSION >= 0x01000102

パラメーター

[in]	ctx	このコールバックを登録するコンテキスト
[in]	events	このコールバックをトリガーする活線挿抜イベントのビット単位フラグ。 libusb_hotplug_event を参照してください
[in]	flags	登録に影響する活線挿抜フラグのビット単位フラグ。 libusb_hotplug_flag を参照してください
[in]	vendor_id	一致するベンダーIDまたは LIBUSB_HOTPLUG_MATCH_ANY
[in]	product_id	一致する製品IDまたは LIBUSB_HOTPLUG_MATCH_ANY
[in]	dev_class	一致するデバイス・クラスまたは LIBUSB_HOTPLUG_MATCH_ANY
[in]	cb_fn	一致するイベントまたはデバイスで呼び出される関数
[in]	user_data	コールバック関数に渡すユーザー・データ
[out]	callback_handle	割り当てられたコールバックのハンドルを格納するためのポインタ(NULLにすることができます)

戻り値

LIBUSB_SUCCESS の場合成功。 LIBUSB_ERROR の場合失敗

libusb_hotplug_deregister_callback()

void libusb_hotplug_deregister_callback	(	libusb_context *	ctx,
		libusb_hotplug_callback_handle	callback_handle
	)

活線挿抜コールバックを登録解除する。

libusb_contextからコールバックの登録を解除します。 この関数は活線挿抜コールバック内から安全に呼び出すことができます。

バージョン 1.0.16 以降。 LIBUSB_API_VERSION >= 0x01000102

パラメーター

[in]	ctx	このコールバックを登録したコンテキスト
[in]	callback_handle	コールバックを登録解除したいハンドル

libusb_hotplug_get_user_data()

void* libusb_hotplug_get_user_data	(	libusb_context *	ctx,
		libusb_hotplug_callback_handle	callback_handle
	)

活線挿抜コールバックに関連付けられたuser_dataを取得します。

バージョン v1.0.24 以降。 LIBUSB_API_VERSION >= 0x01000108

パラメーター

[in]	ctx	このコールバックを登録したコンテキスト
[in]	callback_handle	user_dataを取得したいコールバックのハンドル