This modules provides the following guarantees for working with USB devices:

• You can't reference handles to devices that are closed. In other words: no I/O with closed handles is possible.
• The programmer can specify the region in which devices should remain open. On exit from the region the opened devices will be closed automatically.
• You can't reference handles to configurations that have not been set.
• You can't reference handles to interfaces that have not been claimed.
• Just like with devices, the programmer can specify the region in which interfaces should remain claimed. On exit from the region the claimed interfaces will be released automatically.
• You can't reference handles to alternates that have not been set.
• You can't reference endpoints that don't belong to a setted alternate.
• You can't read from an endpoint with an Out transfer direction.
• You can't write to an endpoint with an In transfer direction.
• You can't read from or write to endpoints with the unsupported transfer types Control and Isochronous. Only I/O with endpoints with the supported Bulk and Interrupt transfer types is allowed.

This modules makes use of a technique called Lightweight monadic regions invented by Oleg Kiselyov and Chung-chieh Shan

See: http://okmij.org/ftp/Haskell/regions.html#light-weight

This technique is implemented in the regions package of which the Control.Monad.Trans.Region module is re-exported by this module.

See the usb-safe-examples package for examples how to use this library:

darcs get http://code.haskell.org/~basvandijk/code/usb-safe-examples

Handy type synonym for a region in which USB devices can be opened which are automatically closed when the region terminates.

You can run a device region with runRegionT.

Handy type synonym for a device region which has IO as its parent region which enables it to be:

• directly executed in IO using runTopRegion,
• concurrently executed in a new thread by forkTopRegion.

Handy type synonym for a regional handle to an opened USB device.

A regional handle to an opened USB device can be created by applying open or with to the USB device you wish to open.

Note that you can also duplicate a regional device handle by applying dup to it.

Perform a USB port reset to reinitialize a device. The system will attempt to restore the previous configuration and alternate settings after the reset has completed.

Note the constraint: pr `ParentOf` cr. This allows this function to be executed in any child region cr of the parent region pr in which the given regional handle was created.

You can only reset a device when all computations passed to setConfig, useActiveConfig and setConfigWhich have been terminated. If you call resetDevice and such a computation is still running a SettingAlreadySet exception is thrown.

If the reset fails, the descriptors change, or the previous state cannot be restored, the device will appear to be disconnected and reconnected. This means that the device handle is no longer valid (you should close it) and rediscover the device. A NotFoundException is raised to indicate that this is the case.

TODO: Think about how to handle the implications of the the previous paragraph!

This is a blocking function which usually incurs a noticeable delay.

Exceptions:

• NotFoundException if re-enumeration is required, or if the device has been disconnected.
• SettingAlreadySet if a configuration has been set using setConfig, useActiveConfig and setConfigWhich.
• Another USBException.

Retrieve the supported configurations from the given regional handle.

Note that the configuration is parameterized by the same region r in which the regional handle was created. This ensures you can never use a configuration outside that region.

Retrieve the supported interfaces from the configuration handle.

Note that the interface is parameterized by the sCfg of the configuration handle it is derived from. This ensures that it can never be returned from the functions that created this configuration handle: setConfig, useActiveConfig and setConfigWhich.

The latter is useful because outside those functions the active configuration may change. If at that moment you still have an interface of the old configuration claiming it would be an error.

Handy type synonym for a region in which interfaces can be claimed which are automatically released when the region terminates.

You can run an interface region with runRegionT.

Handy type synonym for a regional handle to a claimed interface.

A regional handle to a claimed interface can be created by applying claim or with to the interface you wish to claim.

Retrieve the supported alternate settings from the interface handle.

Note that the alternate setting is parameterized by the same type variables as the interface handle. This ensures you can never use an alternate setting outside the region in which the interface handle was created.

Clear the halt/stall condition for an endpoint.

Endpoints with halt status are unable to receive or transmit data until the halt condition is stalled.

You should cancel all pending transfers before attempting to clear the halt condition.

This is a blocking function.

Exceptions:

• NoDeviceException if the device has been disconnected.
• Another USBException.

Handy type synonym for read transfers.

A ReadAction is a function which takes a timeout and a size which defines how many bytes to read. The function returns an action which, when executed, performs the actual read and returns the bytestring that was read paired with an indication if the transfer timed out.

Handy type synonym for write transfers.

A WriteAction is a function which takes a timeout and the bytestring to write. The function returns an action which, when exectued, returns the number of bytes that were actually written paired with an indication if the transfer timed out.

Retrieve a list of supported languages.

This function may throw USBExceptions.

Retrieve a string descriptor from a device.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

This function may throw USBExceptions.

TODO: The following can be made more type-safe!

When I call getStrDesc I would like the type system to guarantee that the given StrIx and LangId actually belong to the given Handle. In other words I would like to get a type error when they are some arbitrary number or come from another device.

Retrieve a string descriptor from a device using the first supported language.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

This function may throw USBExceptions.

Determine if a kernel driver is active on an interface.

If a kernel driver is active, you cannot claim the interface, and libusb will be unable to perform I/O.

Exceptions:

• NoDeviceException if the device has been disconnected.
• Another USBException.

Detach a kernel driver from an interface.

If successful, you will then be able to claim the interface and perform I/O.

Exceptions:

• NotFoundException if no kernel driver was active.
• InvalidParamException if the interface does not exist.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Re-attach an interface's kernel driver, which was previously detached using detachKernelDriver.

Exceptions:

• NotFoundException if no kernel driver was active.
• InvalidParamException if the interface does not exist.
• NoDeviceException if the device has been disconnected.
• BusyException if the driver cannot be attached because the interface is claimed by a program or driver.
• Another USBException.

If a kernel driver is active on the specified interface the driver is detached and the given action is executed. If the action terminates, whether by normal termination or by raising an exception, the kernel driver is attached again. If a kernel driver is not active on the specified interface the action is just executed.

Exceptions:

• NoDeviceException if the device has been disconnected.
• Another USBException.