libusb: Device hotplug event notification

| libusb 1.0.26 A cross-platform user library to access USB devices

Macros | Typedefs | Enumerations | Functions
Device hotplug event notification

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

## Macros
#define | LIBUSB_HOTPLUG_NO_FLAGS 0
| Convenience macro when not using any flags.
#define | LIBUSB_HOTPLUG_MATCH_ANY -1
| Wildcard matching for hotplug events.

## Typedefs
typedef int | libusb_hotplug_callback_handle
| Callback handle. More...
typedef int(* | libusb_hotplug_callback_fn) (libusb_context *ctx, libusb_device *device, libusb_hotplug_event event, void *user_data)
| Hotplug callback function type. More...

## Enumerations
enum | libusb_hotplug_event { LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = (1 << 0) , LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT = (1 << 1) }
| Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102. More...
enum | libusb_hotplug_flag { LIBUSB_HOTPLUG_ENUMERATE = (1 << 0) }
| Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102. More...

## Functions
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)
| Register a hotplug callback function. More...
void | libusb_hotplug_deregister_callback (libusb_context *ctx, libusb_hotplug_callback_handle callback_handle)
| Deregisters a hotplug callback. More...
void * | libusb_hotplug_get_user_data (libusb_context *ctx, libusb_hotplug_callback_handle callback_handle)
| Gets the user_data associated with a hotplug callback. More...

## Detailed Description

This page details how to use the libusb hotplug interface, where available.

Be mindful that not all platforms currently implement hotplug notification and that you should first call on libusb_has_capability() with parameter LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available.

## Typedef Documentation

## ◆ libusb_hotplug_callback_handle

typedef int libusb_hotplug_callback_handle

Callback handle.

Callbacks handles are generated by libusb_hotplug_register_callback() and can be used to deregister callbacks. Callback handles are unique per libusb_context and it is safe to call libusb_hotplug_deregister_callback() on an already deregistered callback.

Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102

For more information, see Device hotplug event notification.

## ◆ libusb_hotplug_callback_fn

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

Hotplug callback function type.

When requesting hotplug event notifications, you pass a pointer to a callback function of this type.

This callback may be called by an internal event thread and as such it is recommended the callback do minimal processing before returning.

libusb will call this function later, when a matching event had happened on a matching device. See Device hotplug event notification for more information.

It is safe to call either libusb_hotplug_register_callback() or libusb_hotplug_deregister_callback() from within a callback function.

Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102

Parameters

  ctx | 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

Returns
  bool whether this callback is finished processing events. returning 1 will cause this callback to be deregistered

## Enumeration Type Documentation

## ◆ libusb_hotplug_event

enum libusb_hotplug_event

Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102.

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

## ◆ libusb_hotplug_flag

enum libusb_hotplug_flag

Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102.

Hotplug flags

Enumerator
LIBUSB_HOTPLUG_ENUMERATE | Arm the callback and fire it for all matching currently attached devices.

## Function Documentation

## ◆ 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
| ) |  |

Register a hotplug callback function.

Register a callback with the libusb_context. The callback will fire when a matching event occurs on a matching device. The callback is armed until either it is deregistered with libusb_hotplug_deregister_callback() or the supplied callback returns 1 to indicate it is finished processing events.

If the LIBUSB_HOTPLUG_ENUMERATE is passed the callback will be called with a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED for all devices already plugged into the machine. Note that libusb modifies its internal device list from a separate thread, while calling hotplug callbacks from libusb_handle_events(), so it is possible for a device to already be present on, or removed from, its internal device list, while the hotplug callbacks still need to be dispatched. This means that when using LIBUSB_HOTPLUG_ENUMERATE, your callback may be called twice for the arrival of the same device, once from libusb_hotplug_register_callback() and once from libusb_handle_events(); and/or your callback may be called for the removal of a device for which an arrived call was never made.

Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102

Parameters

  [in] | ctx | context to register this callback with
  [in] | events | bitwise or of hotplug events that will trigger this callback. See libusb_hotplug_event
  [in] | flags | bitwise or of hotplug flags that affect registration. See libusb_hotplug_flag
  [in] | vendor_id | the vendor id to match or LIBUSB_HOTPLUG_MATCH_ANY
  [in] | product_id | the product id to match or LIBUSB_HOTPLUG_MATCH_ANY
  [in] | dev_class | the device class to match or LIBUSB_HOTPLUG_MATCH_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] | callback_handle | pointer to store the handle of the allocated callback (can be NULL)

Returns
  LIBUSB_SUCCESS on success LIBUSB_ERROR code on failure

## ◆ libusb_hotplug_deregister_callback()

void libusb_hotplug_deregister_callback | ( | libusb_context * | ctx,
|  | libusb_hotplug_callback_handle | callback_handle
| ) |  |

Deregisters a hotplug callback.

Deregister a callback from a libusb_context. This function is safe to call from within a hotplug callback.

Since version 1.0.16, LIBUSB_API_VERSION >= 0x01000102

Parameters

  [in] | ctx | context this callback is registered with
  [in] | callback_handle | the handle of the callback to deregister

## ◆ libusb_hotplug_get_user_data()

void * libusb_hotplug_get_user_data | ( | libusb_context * | ctx,
|  | libusb_hotplug_callback_handle | callback_handle
| ) |  |

Gets the user_data associated with a hotplug callback.

Since version v1.0.24 LIBUSB_API_VERSION >= 0x01000108

Parameters

  [in] | ctx | context this callback is registered with
  [in] | callback_handle | the handle of the callback to get the user_data of