Abstract type representing a USB device detected on the system.

You can only obtain a USB device from the getDevices function.

Certain operations can be performed on a device, but in order to do any I/O you will have to first obtain a DeviceHandle using openDevice.

Just because you have a reference to a device does not mean it is necessarily usable. The device may have been unplugged, you may not have permission to operate such device or another process or driver may be using the device.

To get additional information about a device you can retrieve its descriptor using getDeviceDesc.

Returns a vector of USB devices currently attached to the system.

This is your entry point into finding a USB device.

Exceptions:

• NoMemException on a memory allocation failure.

The set of hotplug events to trigger the callback in registerHotplugCallback.

A device has been plugged in and is ready to use.

A device has left and is no longer available.

It is the user's responsibility to call closeDevice on any handle associated with a disconnected device. It is safe to call getDeviceDesc on a device that has left.

Determine if the set of events contains a deviceArrived event.

Determine if the set of events contains a deviceLeft event.

Set of configuration flags for registerHotplugCallback.

Fire events for all matching currently attached devices.

Hotplug callback function type used in registerHotplugCallback.

libusb will call this function, once registered using registerHotplugCallback, when a matching event has happened on a matching device.

This callback may be called by an internal event thread and as such it is recommended the callback do minimal processing before returning. In fact, it has been observed that doing any I/O with the device from inside the callback results in dead-lock! See the example below on the correct use of this callback.

It is safe to call either registerHotplugCallback or deregisterHotplugCallback from within a callback function.

Should return a CallbackRegistrationStatus which indicates whether this callback is finished processing events. Returning DeregisterThisCallback will cause this callback to be deregistered.

If you need to wait on the arrival of a device after which you need to do something with it, it's recommended to write the device to a concurrent channel like a MVar / TChan / TMVar / TChan / etc. then read the channel outside the callback. This way the processing of the device takes place in a different thread. See the following for one correct use-case:

waitForMyDevice :: Ctx
                -> Maybe VendorId
                -> Maybe ProductId
                -> Maybe Word8
                -> IO Device
waitForMyDevice ctx mbVendorId mbProductId mbDevClass = do
  mv <- newEmptyMVar
  -- We mask asynchronous exceptions to ensure that the callback
  -- gets properly deregistered when an asynchronous exception is
  -- thrown during the interruptible takeMVar operation.
  mask_ $ do
    h <- registerHotplugCallback ctx
                                 deviceArrived
                                 enumerate
                                 mbVendorId
                                 mbProductId
                                 mbDevClass
                                 (\dev event ->
                                    tryPutMVar mv (dev, event) $>
                                      DeregisterThisCallback)
    (dev, _event) <- takeMVar mv
                       `onException`
                         deregisterHotplugCallback h
    return dev

Returned from a HotplugCallback to indicate whether the callback is finished processing events.

Callback handle.

Callbacks handles are generated by registerHotplugCallback and can be used to deregister callbacks. Callback handles are unique per Ctx and it is safe to call deregisterHotplugCallback on an already deregisted callback.

WARNING: see the note on HotplugCallback for the danger of using this function!

Register a hotplug callback function with the context. The callback will fire when a matching event occurs on a matching device. The callback is armed until either it is deregistered with deregisterHotplugCallback or the supplied callback returns DeregisterThisCallback to indicate it is finished processing events.

If the enumerate flag is passed the callback will be called with a deviceArrived 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 the enumerate flag, your callback may be called twice for the arrival of the same device, once from registerHotplugCallback 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.

Deregisters a hotplug callback.

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

The number of the bus that a device is connected to.

Get the number of the port that a is device connected to. Unless the OS does something funky, or you are hot-plugging USB extension cards, the port number returned by this call is usually guaranteed to be uniquely tied to a physical port, meaning that different devices plugged on the same physical port should return the same port number.

But outside of this, there is no guarantee that the port number returned by this call will remain the same, or even match the order in which ports have been numbered by the HUB/HCD manufacturer.

Get the list of all port numbers from root for the specified device.

The address of the device on the bus it is connected to.

Get the negotiated connection speed for a device.

Nothing means that the OS doesn't know or doesn't support returning the negotiated speed.

Speed codes. Indicates the speed at which the device is operating.