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 specifies the region in which devices should remain open. On exit from the region the opened devices are automatically closed.
• You can't reference handles to configurations that have not been set.
• You can't reference handles to interfaces that have not been claimed.
• 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 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

Execute a region inside its parent region pr.

All Devices which have been opened in the given region using openDevice, and which haven't been duplicated using dupDeviceHandle, will be closed on exit from this function wether by normal termination or by raising an exception.

Also all devices which have been duplicated to this region from a child region are closed on exit if they haven't been duplicated themselves.

Note the type variable s of the region wich is only quantified over the region itself. This ensures that no values, that have a type which has s in it, can be returned from this function. (Note the similarity with the ST monad.)

DeviceHandles are parameterized by the region in which they were created. So device handles which were created by openDevice in the given region have this s in their type. This ensures that these device handles, which may have been closed on exit from this function, can't be returned by this function. This ensures you can never do any IO with closed device handles.

Note that it is possible to run a region inside another region.

TODO: Say something more about this nesting of regions...

Convenience funtion for running a top-level region in IO.

Note that: runTopDeviceRegion = runDeviceRegionT

Return a region which executes the given top-level region in a new thread.

Note that the forked region has the same type variable s as the resulting region. This means that all DeviceHandles which can be referenced in the resulting region can also be referenced in the forked region.

Open a device in a region.

Note that the returned device handle is parameterized by the region in which it was created. This is to ensure that device handles can never escape their region and to support operations on device handles that are used in a child region of the region in which the device was created.

This is a non-blocking function; no requests are sent over the bus.

Exceptions:

• NoMemException if there is a memory allocation failure.
• AccessException if the user has insufficient permissions.
• NoDeviceException if the device has been disconnected.
• Another USBException.

A convenience function which opens the given device, applies the given function to the resulting device handle and runs the resulting region.

Note that: withDevice dev f = runDeviceRegionT $ openDevice dev >>= f

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 pr `ParentOf` cr which ensures that this function can be executed in any child region of the region in which the given device handle was created.

You can only reset a device when all computations passed to withConfig or withActiveConfig 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 withConfig or withActiveConfig.
• Another USBException.

Retrieve the supported configurations from the device handle.

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

Set the active configuration for a device and then apply the given function to the resulting configuration handle.

USB devices support multiple configurations of which only one can be active at any given time. When a configuration is set using withConfig or withActiveConfig no threads can set a new configuration until the computation passed to these functions terminates. If you do try to set one a SettingAlreadySet exception will be thrown.

The operating system may or may not have already set an active configuration on the device. It is up to your application to ensure the correct configuration is selected before you attempt to claim interfaces and perform other operations. If you want to use the current active configuration use withActiveConfig.

If you call this function on a device already configured with the selected configuration, then this function will act as a lightweight device reset: it will issue a SET_CONFIGURATION request using the current configuration, causing most USB-related device state to be reset (altsetting reset to zero, endpoint halts cleared, toggles reset).

You cannot change/reset configuration if other applications or drivers have claimed interfaces.

This is a blocking function.

Exceptions:

• BusyException if interfaces are currently claimed.
• NoDeviceException if the device has been disconnected
• SettingAlreadySet if a configuration has already been set using withConfig or withActiveConfig.
• Another USBException.

Apply the given function to the configuration handle of the current active configuration of the given device handle.

This function needs to determine the current active configuration. This information may be cached by the operating system. If it isn't cached this function will block while a control transfer is submitted to retrieve the information.

TODO: I'm not yet sure if this is the best way of handling already configured devices. So this may change in the future!

Exceptions:

• NoDeviceException if the device has been disconnected.
• SettingAlreadySet if a configuration has already been set using withConfig or withActiveConfig.
• NoActiveConfig if the device is not configured.
• Aanother USBException.

Retrieve the supported interfaces from the configuration handle.

Note that the interface is parameterized by the same type variables as the configuration handle. This ensures you can never use an interface outside the scope of the function passed to withConfig or withActiveConfig.

Retrieve the alternate interface descriptors of the interface.

Note that: type Interface = [InterfaceDesc].

Claim the given interface, then apply the given function to the resulting interface handle and finally release the interface on exit from the function wether by normal termination or by raising an exception.

Note that it is allowed to claim an already-claimed interface.

Claiming of interfaces is a purely logical operation; it does not cause any requests to be sent over the bus. Interface claiming is used to instruct the underlying operating system that your application wishes to take ownership of the interface.

This is a non-blocking function.

Exceptions:

• BusyException if the interface is already claimed.
• NoDeviceException if the device has been disconnected.
• Another USBException.

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 scope of the function passed to withInterface.

Activate an alternate setting for an interface and then apply the given function to the resulting alternate handle.

Simillary to configurations, interfaces support multiple alternate settings of which only one can be active at any given time. When an alternate is set using withAlternate or withActiveAlternate no threads can set a new alternate until the computation passed to these functions terminates. If you do try to set one a SettingAlreadySet exception will be thrown.

The operating system may already have set an alternate for the interface. If you want to use this current active alternate use withActiveAlternate.

This is a blocking function.

Exceptions:

• NoDeviceException if the device has been disconnected.
• SettingAlreadySet if an alternate has already been set using withAlternate or withActiveAlternate.
• Another USBException.

Apply the given function to the alternate handle of the current active alternate of the give interface handle.

To determine the current active alternate this function will block while a control transfer is submitted to retrieve the information.

TODO: I'm not yet sure if this is the best way of handling already configured devices. So this may change in the future!

Exceptions:

• NoDeviceException if the device has been disconnected.
• SettingAlreadySet if an alternate has already been set using withAlternate or withActiveAlternate.
• Aanother USBException.

Retrieve the supported endpoints from the alternate handle.

Note that the endpoint is parameterized by the same type variables as the alternate handle. This ensures you can never use an endpoint outside the scope of the function passed to withAlternate or withActiveAlternate.

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 DeviceHandle. 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.