Device hotplug event notification

This page details how to use the libusb hotplug interface. More...

Typedefs
typedef struct libusb_hotplug_callback	libusb_hotplug_callback
	Structure representing a libusb hotplug callback.
typedef void(*	libusb_hotplug_callback_fn )(libusb_context *ctx, libusb_device *device, libusb_hotplug_event event, void *user_data)
	Hotplug callback function type.

Enumerations
enum	libusb_hotplug_flag { LIBUSB_HOTPLUG_PERSIST = 0, LIBUSB_HOTPLUG_ONCE = 1, LIBUSB_HOTPLUG_FREE = 2 }
	Flags for hotplug events. More...
enum	libusb_hotplug_event { LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01, LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT = 0x02 }
	Hotplug events. More...
enum	{ LIBUSB_HOTPLUG_CLASS_ANY = -1, LIBUSB_HOTPLUG_VENDORID_ANY = -2, LIBUSB_HOTPLUG_PRODUCTID_ANY = -3 }
	Wildcard matching for hotplug events. More...

Functions
int	libusb_hotplug_alloc_callback (libusb_hotplug_event event, libusb_hotplug_flag flags, int vendor_id, int product_id, int dev_class, libusb_hotplug_callback_fn cb_fn, void *user_data, libusb_hotplug_callback **cb)
	Allocate and prepare a hotplug callback.
void	libusb_hotplug_free_callback (libusb_hotplug_callback **cb)
	Free an allocated callback.
void	libusb_hotplug_register_callback (libusb_context *ctx, libusb_hotplug_callback *cb)
	Registers a prepared hotplug callback.
void	libusb_hotplug_deregister_callback (libusb_context *ctx, libusb_hotplug_callback *cb)
	Deregisters a hotplug callback.

---

Detailed Description

This page details how to use the libusb hotplug interface.

---

Typedef Documentation

typedef struct libusb_hotplug_callback libusb_hotplug_callback

Structure representing a libusb hotplug callback.

Callbacks are created by libusb_hotplug_alloc_callback() and freed by libusb_hotplug_free_callback().

For more information, see Device hotplug event notification.

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

Hotplug callback function type.

When requesting hotplug support, you pass a pointer to a callback function of this type. libusb will call this function later, when a matching device has been connected. See Device hotplug event notification for more information.

Parameters:

libusb_context	context of this notification
device	libusb_device this event occurred on
event	event that occurred
user_data	user data provided when this callback was registered

---

Enumeration Type Documentation

enum libusb_hotplug_flag

Flags for hotplug events.

Enumerator:

LIBUSB_HOTPLUG_PERSIST	The hotplug event will persist until removed with libusb_hotplug_deregister_callback() or libusb_exit()
LIBUSB_HOTPLUG_ONCE	The hotplug callback will fire once and be deregistered. It is safe to free the callback in the callback function if this flag is set.
LIBUSB_HOTPLUG_FREE	Automatically free the callback once it has been deregistered.

enum libusb_hotplug_event

Hotplug events.

Enumerator:

LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED	A device has been plugged in and is ready to use.
LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT	A device has left and is no longer available. It is the user's responsibility to call libusb_close on any handle associated with a disconnected device. It is safe to call libusb_get_device_descriptor on a device that has left

anonymous enum

Wildcard matching for hotplug events.

Enumerator:

LIBUSB_HOTPLUG_CLASS_ANY	Match any device class.
LIBUSB_HOTPLUG_VENDORID_ANY	Match any vendor id.
LIBUSB_HOTPLUG_PRODUCTID_ANY	Match any product id.

---

Function Documentation

int libusb_hotplug_alloc_callback	(	libusb_hotplug_event	event,
		libusb_hotplug_flag	flags,
		int	vendor_id,
		int	product_id,
		int	dev_class,
		libusb_hotplug_callback_fn	cb_fn,
		void *	user_data,
		libusb_hotplug_callback **	cb
	)

Allocate and prepare a hotplug callback.

Parameters:

[in]	event	the events that will trigger this callback
[in]	flags	hotplug callback flags (described above)
[in]	vendor_id	the vendor id to match or LIBUSB_HOTPLUG_PRODUCTID_ANY
[in]	product_id	the product id to match or LIBUSB_HOTPLUG_PRODUCTID_ANY
[in]	dev_class	the device class to match or LIBUSB_HOTPLUG_CLASS_ANY
[in]	cb_fn	the function to be invoked on a matching event/device
[in]	user_data	user data to pass to the callback function
[out]	cb	allocated callback on success

Returns:

LIBUSB_SUCCESS on success LIBUSB_ERROR code on failure

void libusb_hotplug_free_callback

(

libusb_hotplug_callback **

cb

)

Free an allocated callback.

This call will deregister the callback if it is still registered and is not safe to call inside a callback.

cb is set to NULL after completion

Parameters:

[in,out]

cb

pointer to a callback to free

void libusb_hotplug_register_callback	(	libusb_context *	ctx,
		libusb_hotplug_callback *	cb
	)

Registers a prepared hotplug callback.

A callback can only be registered with a single context.

Parameters:

[in]	ctx	context to register this callback with
[in]	cb	the callback to register

void libusb_hotplug_deregister_callback	(	libusb_context *	ctx,
		libusb_hotplug_callback *	cb
	)

Deregisters a hotplug callback.

Do not call this function from within a callback function. This will result in deadlock.

Parameters:

[in]	ctx	context this callback was registered with
[in]	cb	the callback to deregister