A regional handle to an opened USB device.

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

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

Convenience function which finds the first device attached to the system which satisfies the given predicate on its descriptor, then opens that device and applies the given continuation function to the resulting device handle.

Exceptions:

• NotFoundException if no device is found which satisfies the given predicate.
• 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 supported configuration of a USB device parameterized by the region r in which it was created.

Note that, just like a regional device handle, a configuration can be duplicated to a parent region using dup.

Also note that you can get the descriptor of the configuration by applying getDesc to it.

A handle to an active Config which you can get using: setConfig, useActiveConfig or setConfigWhich.

The type variable sCfg is used to ensure that you can't return this handle from these functions.

Set the active configuration for a device and then apply the given continuation 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 setConfig, useActiveConfig or setConfigWhich 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 useActiveConfig.

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:

• SettingAlreadySet if a configuration has already been set using setConfig, useActiveConfig or setConfigWhich.
• BusyException if interfaces are currently claimed.
• NoDeviceException if the device has been disconnected
• Another USBException.

This exception can be thrown in:

• resetDevice
• setConfig, useActiveConfig or setConfigWhich
• setAlternate, useActiveAlternate or setAlternateWhich

to indicate that the device was already configured with a setting.

Apply the given continuation 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.

Exceptions:

• SettingAlreadySet if a configuration has already been set using setConfig, useActiveConfig or setConfigWhich.
• NoActiveConfig if the device is not configured.
• NoDeviceException if the device has been disconnected.
• Aanother USBException.

Convenience function which finds the first configuration of the given device handle which satisfies the given predicate on its descriptor, then sets that configuration and applies the given function to the resulting configuration handle.

This function calls setConfig so do see its documentation.

Exceptions:

• SettingAlreadySet if a configuration has already been set using setConfig, useActiveConfig or setConfigWhich.
• NotFoundException if no configuration is found that satisfies the given predicate.
• BusyException if interfaces are currently claimed.
• NoDeviceException if the device has been disconnected
• Another USBException.

A supported interface of a configuration which you can retrieve using getInterfaces.

To retrieve the Interface descriptors of an interface use getDesc.

A regional handle to a claimed interface.

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

Claim the given interface in the region. When the region terminates the interface is released automatically.

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 another program or driver has claimed the interface.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Convenience function which finds the first interface of the given configuration handle which satisfies the given predicate on its descriptors, then claims that interfaces and applies the given continuation function to the resulting regional handle.

Exceptions:

• NotFoundException if no interface was found that satisfies the fiven predicate.
• BusyException if another program or driver has claimed the interface.
• NoDeviceException if the device has been disconnected.
• Another USBException.

A handle to a setted alternate setting.

You get a handle to an alternate using setAlternate, useActiveAlternate or setAlternateWhich. The type variable sAlt is used to ensure that you can't return this handle from these functions.

Activate an alternate setting for an interface and then apply the given continuation 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 setAlternate, useActiveAlternate or setAlternateWhich 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 useActiveAlternate.

This is a blocking function.

Exceptions:

• NoDeviceException if the device has been disconnected.
• SettingAlreadySet if an alternate has already been set using setAlternate, useActiveAlternate or setAlternateWhich.
• 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.

Exceptions:

• NoDeviceException if the device has been disconnected.
• SettingAlreadySet if an alternate has already been set using setAlternate, useActiveAlternate or setAlternateWhich.
• Another USBException.

Convenience function which finds the first alternate of the given interface handle which satisfies the given predicate on its descriptor, then sets that alternate and applies the given function to the resulting alternate handle.

This function calls setAlternate so do see its documentation.

Exceptions:

• NotFoundException if no alternate is found that satisfies the given predicate.
• NoDeviceException if the device has been disconnected.
• SettingAlreadySet if an alternate has already been set using setAlternate, useActiveAlternate or setAlternateWhich.
• Another USBException.

I/O operations on endpoints are type-safe. You can only read from an endpoint with an In transfer direction and you can only write to an endpoint with an Out transfer direction.

Reading and writing also have different implementations for the different endpoint transfer types like: Bulk and Interrupt. I/O with endpoints of other transfer types like Control and Isochronous is not possible.

This type lifts the transfer direction and transfer type information to the type-level so that I/O operations like readEndpoint and writeEndpoint can specify which endpoints they support.

You can retrieve the endpoints of an alternate using getEndpoints.

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.