-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Communicate with USB devices -- -- This library enables you to communicate with USB devices from -- userspace. It is implemented as a high-level wrapper around -- bindings-libusb which is a low-level binding to the C -- library: libusb-1.*. -- -- The USB transfer functions in this library have a simple synchronous -- interface (they block) but are implemented using the libusb -- asynchronous interface. They integrate with the GHC event manager -- making them efficient (no busy-loops) and interruptible (throwing an -- exception to the thread executing a transfer immediately cancels the -- transfer). -- -- If the GHC event manager is not available (because you're either not -- using GHC or because you're on Windows) the library degrades -- gracefully to the libusb synchronous implementation. -- -- This documentation assumes knowledge of how to operate USB devices -- from a software standpoint (descriptors, configurations, interfaces, -- endpoints, control/bulk/interrupt/isochronous transfers, etc). Full -- information can be found in the USB 2.0 Specification. -- -- For an example how to use this library see the usb-example -- package at: -- -- https://github.com/basvandijk/usb-example -- -- or the ls-usb package at: -- -- http://hackage.haskell.org/package/ls-usb -- -- Also see the usb-safe package which wraps this package and -- provides some strong safety guarantees for working with USB devices: -- -- http://hackage.haskell.org/package/usb-safe -- -- Finally have a look at the usb-iteratee package which -- provides iteratee enumerators for enumerating bulk, interrupt -- and isochronous endpoints: -- -- http://hackage.haskell.org/package/usb-iteratee -- -- Besides this API documentation the following sources might be -- interesting: -- -- @package usb @version 1.1 -- | This module provides functionality for initializing the usb -- library. module System.USB.Initialization -- | Abstract type representing a USB session. -- -- The concept of individual sessions allows your program to use multiple -- threads that can independently use this library without interfering -- with eachother. -- -- Sessions are created and initialized by newCtx and are -- automatically closed when they are garbage collected. -- -- The only functions that receive a Ctx are setDebug and -- getDevices. data Ctx -- | Create and initialize a new USB context. -- -- This function may throw USBExceptions. -- -- Note that the internal libusb event handling can return -- errors. These errors occur in the thread that is executing the event -- handling loop. newCtx will print these errors to stderr. -- If you need to handle the errors yourself (for example log them in an -- application specific way) please use newCtx'. newCtx :: IO Ctx -- | Like newCtx but enables you to specify the way errors should be -- handled that occur while handling libusb events. newCtx' :: (USBException -> IO ()) -> IO Ctx -- | Set message verbosity. -- -- The default level is PrintNothing. This means no messages are -- ever printed. If you choose to increase the message verbosity level -- you must ensure that your application does not close the -- stdout/stderr file descriptors. -- -- You are advised to set the debug level to PrintWarnings. Libusb -- is conservative with its message logging. Most of the time it will -- only log messages that explain error conditions and other oddities. -- This will help you debug your software. -- -- The LIBUSB_DEBUG environment variable overrules the debug level set by -- this function. The message verbosity is fixed to the value in the -- environment variable if it is defined. -- -- If libusb was compiled without any message logging, this -- function does nothing: you'll never get any messages. -- -- If libusb was compiled with verbose debug message logging, -- this function does nothing: you'll always get messages from all -- levels. setDebug :: Ctx -> Verbosity -> IO () -- | Message verbosity data Verbosity -- | No messages are ever printed by the library PrintNothing :: Verbosity -- | Error messages are printed to stderr PrintErrors :: Verbosity -- | Warning and error messages are printed to stderr PrintWarnings :: Verbosity -- | Informational messages are printed to stdout, warning and error -- messages are printed to stderr PrintInfo :: Verbosity -- | This module provides functionality for enumerating the USB devices -- currently attached to the system. module System.USB.Enumeration -- | 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. Alternatively you can use the usb-safe -- package which provides type-safe device handling. See: -- -- http://hackage.haskell.org/package/usb-safe -- -- 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 deviceDesc. data Device -- | Returns a list of USB devices currently attached to the system. -- -- This is your entry point into finding a USB device. -- -- Exceptions: -- -- getDevices :: Ctx -> IO [Device] -- | The number of the bus that a device is connected to. busNumber :: Device -> Word8 -- | The address of the device on the bus it is connected to. deviceAddress :: Device -> Word8 -- | Get the descriptor of the device. deviceDesc :: Device -> DeviceDesc -- | The module provides functionality for opening, closing and configuring -- USB devices. module System.USB.DeviceHandling -- | Abstract type representing a handle of a USB device. -- -- You can acquire a handle from openDevice. -- -- A device handle is used to perform I/O and other operations. When -- finished with a device handle you should close it by applying -- closeDevice to it. data DeviceHandle -- | Open a device and obtain a device handle. -- -- A handle allows you to perform I/O on the device in question. -- -- This is a non-blocking function; no requests are sent over the bus. -- -- It is advisable to use withDeviceHandle because it -- automatically closes the device when the computation terminates. -- -- Exceptions: -- -- openDevice :: Device -> IO DeviceHandle -- | Close a device handle. -- -- Should be called on all open handles before your application exits. -- -- This is a non-blocking function; no requests are sent over the bus. closeDevice :: DeviceHandle -> IO () -- | withDeviceHandle dev act opens the Device dev -- and passes the resulting handle to the computation act. The -- handle will be closed on exit from withDeviceHandle whether -- by normal termination or by raising an exception. withDeviceHandle :: Device -> (DeviceHandle -> IO α) -> IO α -- | Retrieve the Device from the DeviceHandle. getDevice :: DeviceHandle -> Device -- | Identifier for configurations. -- -- Can be retrieved by getConfig or by configValue. type ConfigValue = Word8 -- | Determine the value of the currently active configuration. -- -- You could formulate your own control request to obtain this -- information, but this function has the advantage that it may be able -- to retrieve the information from operating system caches (no I/O -- involved). -- -- If the OS does not cache this information, then this function will -- block while a control transfer is submitted to retrieve the -- information. -- -- This function returns Nothing if the device is in unconfigured -- state. -- -- Exceptions: -- -- getConfig :: DeviceHandle -> IO (Maybe ConfigValue) -- | Set the active configuration for a device. -- -- 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 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 your application has claimed -- interfaces - you should free them with releaseInterface first. -- You cannot change/reset configuration if other applications or drivers -- have claimed interfaces. -- -- A configuration value of Nothing will put the device in an -- unconfigured state. The USB specification states that a configuration -- value of 0 does this, however buggy devices exist which actually have -- a configuration 0. -- -- You should always use this function rather than formulating your own -- SET_CONFIGURATION control request. This is because the underlying -- operating system needs to know when such changes happen. -- -- This is a blocking function. -- -- Exceptions: -- -- setConfig :: DeviceHandle -> Maybe ConfigValue -> IO () -- | Identifier for interfaces. -- -- Can be retrieved by interfaceNumber. type InterfaceNumber = Word8 -- | Claim an interface on a given device handle. -- -- You must claim the interface you wish to use before you can perform -- I/O on any of its endpoints. -- -- It is legal to attempt to claim an already-claimed interface, in which -- case this function just returns without doing anything. -- -- 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: -- -- claimInterface :: DeviceHandle -> InterfaceNumber -> IO () -- | Release an interface previously claimed with claimInterface. -- -- You should release all claimed interfaces before closing a device -- handle. -- -- This is a blocking function. A SET_INTERFACE control request will be -- sent to the device, resetting interface state to the first alternate -- setting. -- -- Exceptions: -- -- releaseInterface :: DeviceHandle -> InterfaceNumber -> IO () -- | withClaimedInterface claims the interface on the given device -- handle then executes the given computation. On exit from -- withClaimedInterface, the interface is released whether by -- normal termination or by raising an exception. withClaimedInterface :: DeviceHandle -> InterfaceNumber -> IO α -> IO α -- | Identifier for interface alternate settings. -- -- Can be retrieved by interfaceAltSetting. type InterfaceAltSetting = Word8 -- | Activate an alternate setting for an interface. -- -- The interface must have been previously claimed with -- claimInterface or withInterfaceHandle. -- -- You should always use this function rather than formulating your own -- SET_INTERFACE control request. This is because the underlying -- operating system needs to know when such changes happen. -- -- This is a blocking function. -- -- Exceptions: -- -- setInterfaceAltSetting :: DeviceHandle -> InterfaceNumber -> InterfaceAltSetting -> IO () -- | 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: -- -- clearHalt :: DeviceHandle -> EndpointAddress -> IO () -- | 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. -- -- 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. -- -- This is a blocking function which usually incurs a noticeable delay. -- -- Exceptions: -- -- resetDevice :: DeviceHandle -> IO () -- | 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: -- -- kernelDriverActive :: DeviceHandle -> InterfaceNumber -> IO Bool -- | Detach a kernel driver from an interface. -- -- If successful, you will then be able to claim the interface and -- perform I/O. -- -- Exceptions: -- -- detachKernelDriver :: DeviceHandle -> InterfaceNumber -> IO () -- | Re-attach an interface's kernel driver, which was previously detached -- using detachKernelDriver. -- -- Exceptions: -- -- attachKernelDriver :: DeviceHandle -> InterfaceNumber -> IO () -- | 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: -- -- withDetachedKernelDriver :: DeviceHandle -> InterfaceNumber -> IO α -> IO α -- | USB devices report their attributes using descriptors. A descriptor is -- a data structure with a defined format. Using descriptors allows -- concise storage of the attributes of individual configurations because -- each configuration may reuse descriptors or portions of descriptors -- from other configurations that have the same characteristics. In this -- manner, the descriptors resemble individual data records in a -- relational database. -- -- Where appropriate, descriptors contain references to string -- descriptors (StrIx) that provide textual information describing -- a descriptor in human-readable form. Note that the inclusion of string -- descriptors is optional. module System.USB.Descriptors -- | A structure representing the standard USB device descriptor. -- -- This descriptor is documented in section 9.6.1 of the USB 2.0 -- specification. -- -- This structure can be retrieved by deviceDesc. data DeviceDesc DeviceDesc :: !ReleaseNumber -> !Word8 -> !Word8 -> !Word8 -> !Word8 -> !VendorId -> !ProductId -> !ReleaseNumber -> !Maybe StrIx -> !Maybe StrIx -> !Maybe StrIx -> !Word8 -> ![ConfigDesc] -> DeviceDesc -- | USB specification release number. deviceUSBSpecReleaseNumber :: DeviceDesc -> !ReleaseNumber -- | USB-IF class code for the device. deviceClass :: DeviceDesc -> !Word8 -- | USB-IF subclass code for the device, qualified by the -- deviceClass value. deviceSubClass :: DeviceDesc -> !Word8 -- | USB-IF protocol code for the device, qualified by the -- deviceClass and deviceSubClass values. deviceProtocol :: DeviceDesc -> !Word8 -- | Maximum packet size for endpoint 0. deviceMaxPacketSize0 :: DeviceDesc -> !Word8 -- | USB-IF vendor ID. deviceVendorId :: DeviceDesc -> !VendorId -- | USB-IF product ID. deviceProductId :: DeviceDesc -> !ProductId -- | Device release number. deviceReleaseNumber :: DeviceDesc -> !ReleaseNumber -- | Optional index of string descriptor describing manufacturer. deviceManufacturerStrIx :: DeviceDesc -> !Maybe StrIx -- | Optional index of string descriptor describing product. deviceProductStrIx :: DeviceDesc -> !Maybe StrIx -- | Optional index of string descriptor containing device serial number. deviceSerialNumberStrIx :: DeviceDesc -> !Maybe StrIx -- | Number of possible configurations. deviceNumConfigs :: DeviceDesc -> !Word8 -- | List of configurations supported by the device. deviceConfigs :: DeviceDesc -> ![ConfigDesc] type ReleaseNumber = (Int, Int, Int, Int) type VendorId = Word16 type ProductId = Word16 -- | A structure representing the standard USB configuration descriptor. -- -- This descriptor is documented in section 9.6.3 of the USB 2.0 -- specification. -- -- This structure can be retrieved by deviceConfigs. data ConfigDesc ConfigDesc :: !ConfigValue -> !Maybe StrIx -> !ConfigAttribs -> !Word8 -> !Word8 -> ![Interface] -> !ByteString -> ConfigDesc -- | Identifier value for the configuration. configValue :: ConfigDesc -> !ConfigValue -- | Optional index of string descriptor describing the configuration. configStrIx :: ConfigDesc -> !Maybe StrIx -- | Configuration characteristics. configAttribs :: ConfigDesc -> !ConfigAttribs -- | Maximum power consumption of the USB device from the bus in the -- configuration when the device is fully operational. Expressed in 2 mA -- units (i.e., 50 = 100 mA). configMaxPower :: ConfigDesc -> !Word8 -- | Number of interfaces supported by the configuration. configNumInterfaces :: ConfigDesc -> !Word8 -- | List of interfaces supported by the configuration. Note that the -- length of this list should equal configNumInterfaces. configInterfaces :: ConfigDesc -> ![Interface] -- | Extra descriptors. If libusb encounters unknown configuration -- descriptors, it will store them here, should you wish to parse them. configExtra :: ConfigDesc -> !ByteString -- | An interface is represented as a list of alternate interface settings. type Interface = [InterfaceDesc] -- | The USB 2.0 specification specifies that the configuration attributes -- only describe the device status. type ConfigAttribs = DeviceStatus data DeviceStatus DeviceStatus :: !Bool -> !Bool -> DeviceStatus -- | The Remote Wakeup field indicates whether the device is currently -- enabled to request remote wakeup. The default mode for devices that -- support remote wakeup is disabled. remoteWakeup :: DeviceStatus -> !Bool -- | The Self Powered field indicates whether the device is currently -- self-powered selfPowered :: DeviceStatus -> !Bool -- | A structure representing the standard USB interface descriptor. -- -- This descriptor is documented in section 9.6.5 of the USB 2.0 -- specification. -- -- This structure can be retrieved using configInterfaces. data InterfaceDesc InterfaceDesc :: !InterfaceNumber -> !InterfaceAltSetting -> !Word8 -> !Word8 -> !Word8 -> !Maybe StrIx -> ![EndpointDesc] -> !ByteString -> InterfaceDesc -- | Number of the interface. interfaceNumber :: InterfaceDesc -> !InterfaceNumber -- | Value used to select the alternate setting for the interface. interfaceAltSetting :: InterfaceDesc -> !InterfaceAltSetting -- | USB-IF class code for the interface. interfaceClass :: InterfaceDesc -> !Word8 -- | USB-IF subclass code for the interface, qualified by the -- interfaceClass value. interfaceSubClass :: InterfaceDesc -> !Word8 -- | USB-IF protocol code for the interface, qualified by the -- interfaceClass and interfaceSubClass values. interfaceProtocol :: InterfaceDesc -> !Word8 -- | Optional index of string descriptor describing the interface. interfaceStrIx :: InterfaceDesc -> !Maybe StrIx -- | List of endpoints supported by the interface. interfaceEndpoints :: InterfaceDesc -> ![EndpointDesc] -- | Extra descriptors. If libusb encounters unknown interface -- descriptors, it will store them here, should you wish to parse them. interfaceExtra :: InterfaceDesc -> !ByteString -- | A structure representing the standard USB endpoint descriptor. -- -- This descriptor is documented in section 9.6.3 of the USB 2.0 -- specification. -- -- This structure can be retrieved by using interfaceEndpoints. data EndpointDesc EndpointDesc :: !EndpointAddress -> !EndpointAttribs -> !MaxPacketSize -> !Word8 -> !Word8 -> !Word8 -> !ByteString -> EndpointDesc -- | The address of the endpoint described by the descriptor. endpointAddress :: EndpointDesc -> !EndpointAddress -- | Attributes which apply to the endpoint when it is configured using the -- configValue. endpointAttribs :: EndpointDesc -> !EndpointAttribs -- | Maximum packet size the endpoint is capable of sending/receiving. endpointMaxPacketSize :: EndpointDesc -> !MaxPacketSize -- | Interval for polling endpoint for data transfers. Expressed in frames -- or microframes depending on the device operating speed (i.e., either 1 -- millisecond or 125 μs units). endpointInterval :: EndpointDesc -> !Word8 -- | For audio devices only: the rate at which synchronization -- feedback is provided. endpointRefresh :: EndpointDesc -> !Word8 -- | For audio devices only: the address of the synch endpoint. endpointSynchAddress :: EndpointDesc -> !Word8 -- | Extra descriptors. If libusb encounters unknown endpoint -- descriptors, it will store them here, should you wish to parse them. endpointExtra :: EndpointDesc -> !ByteString -- | The address of an endpoint. data EndpointAddress EndpointAddress :: !Int -> !TransferDirection -> EndpointAddress -- | Must be >= 0 and <= 15 endpointNumber :: EndpointAddress -> !Int transferDirection :: EndpointAddress -> !TransferDirection -- | The direction of data transfer relative to the host. data TransferDirection -- | Out transfer direction (host -> device) used for writing. Out :: TransferDirection -- | In transfer direction (device -> host) used for reading. In :: TransferDirection -- | The USB 2.0 specification specifies that the endpoint attributes only -- describe the endpoint transfer type. type EndpointAttribs = TransferType -- | Describes what types of transfers are allowed on the endpoint. data TransferType -- | Control transfers are typically used for command and status -- operations. Control :: TransferType -- | Isochronous transfers occur continuously and periodically. Isochronous :: !Synchronization -> !Usage -> TransferType -- | Bulk transfers can be used for large bursty data. Bulk :: TransferType -- | Interrupt transfers are typically non-periodic, small device -- "initiated" communication requiring bounded latency. Interrupt :: TransferType -- | See section 5.12.4.1 of the USB 2.0 specification. data Synchronization NoSynchronization :: Synchronization -- | Unsynchronized, although sinks provide data rate feedback. Asynchronous :: Synchronization -- | Synchronized using feedback or feedforward data rate information Adaptive :: Synchronization -- | Synchronized to the USBs SOF (Start Of Frame) Synchronous :: Synchronization -- | See section 5.12.4.2 of the USB 2.0 specification. data Usage Data :: Usage Feedback :: Usage Implicit :: Usage data MaxPacketSize MaxPacketSize :: !Size -> !TransactionOpportunities -> MaxPacketSize maxPacketSize :: MaxPacketSize -> !Size transactionOpportunities :: MaxPacketSize -> !TransactionOpportunities -- | Number of additional transaction oppurtunities per microframe. -- -- See table 9-13 of the USB 2.0 specification. data TransactionOpportunities -- | None (1 transaction per microframe) Zero :: TransactionOpportunities -- | 1 additional (2 per microframe) One :: TransactionOpportunities -- | 2 additional (3 per microframe) Two :: TransactionOpportunities -- | Calculate the maximum packet size which a specific endpoint is capable -- of sending or receiving in the duration of 1 microframe. -- -- If acting on an Isochronous or Interrupt endpoint, this -- function will multiply the maxPacketSize by the additional -- transactionOpportunities. If acting on another type of endpoint -- only the maxPacketSize is returned. -- -- This function is mainly useful for setting up isochronous -- transfers. maxIsoPacketSize :: EndpointDesc -> Size -- | Retrieve a list of supported languages. -- -- This function may throw USBExceptions. getLanguages :: DeviceHandle -> IO [LangId] -- | The language ID consists of the primary language identifier and the -- sublanguage identififier as described in: -- -- http://www.usb.org/developers/docs/USB_LANGIDs.pdf -- -- For a mapping between IDs and languages see the -- usb-id-database package at: -- -- http://hackage.haskell.org/package/usb-id-database -- -- To see which LangIds are supported by a device see -- getLanguages. type LangId = (PrimaryLangId, SubLangId) type PrimaryLangId = Word16 type SubLangId = Word16 -- | Type of indici of string descriptors. -- -- Can be retrieved by all the *StrIx functions. type StrIx = Word8 -- | Retrieve a string descriptor from a device. -- -- This function may throw USBExceptions. getStrDesc :: DeviceHandle -> StrIx -> LangId -> Int -> IO Text -- | Retrieve a string descriptor from a device using the first supported -- language. -- -- This function may throw USBExceptions. getStrDescFirstLang :: DeviceHandle -> StrIx -> Int -> IO Text -- | This module provides functions for performing control, -- bulk and interrupt transfers. -- -- When your system supports the GHC EventManager this module -- additionally exports functions for performing isochronous -- transfers. These are currently not available on Windows. -- -- WARNING: You need to enable the threaded runtime -- (-threaded) when using the isochronous functions. They throw -- a runtime error otherwise! module System.USB.IO -- | Handy type synonym for read transfers. -- -- A ReadAction is a function which takes a Size which -- defines how many bytes to read and a Timeout. The function -- returns an IO action which, when executed, performs the actual -- read and returns the ByteString that was read paired with a -- Status flag which indicates whether the transfer -- Completed or TimedOut. type ReadAction = Size -> Timeout -> IO (ByteString, Status) -- | Handy type synonym for read transfers that must exactly read the -- specified number of bytes. An incompleteReadException is thrown -- otherwise. type ReadExactAction = Size -> Timeout -> IO ByteString -- | Handy type synonym for write transfers. -- -- A WriteAction is a function which takes a ByteString -- to write and a Timeout. The function returns an IO -- action which, when exectued, returns the number of bytes that were -- actually written paired with a Status flag which indicates -- whether the transfer Completed or TimedOut. type WriteAction = ByteString -> Timeout -> IO (Size, Status) -- | Handy type synonym for write transfers that must exactly write all the -- given bytes. An incompleteWriteException is thrown otherwise. type WriteExactAction = ByteString -> Timeout -> IO () -- | Number of bytes transferred. type Size = Int -- | A timeout in milliseconds. A timeout defines how long a transfer -- should wait before giving up due to no response being received. Use -- noTimeout for no timeout. type Timeout = Int -- | A timeout of 0 denotes no timeout so: noTimeout = 0. noTimeout :: Timeout -- | Status of a terminated transfer. data Status -- | All bytes were transferred within the maximum allowed Timeout -- period. Completed :: Status -- | Not all bytes were transferred within the maximum allowed -- Timeout period. TimedOut :: Status -- | Handy type synonym that names the parameters of a control transfer. type ControlAction α = RequestType -> Recipient -> Request -> Value -> Index -> α data RequestType Standard :: RequestType Class :: RequestType Vendor :: RequestType data Recipient ToDevice :: Recipient ToInterface :: Recipient ToEndpoint :: Recipient ToOther :: Recipient type Request = Word8 -- | (Host-endian) type Value = Word16 -- | (Host-endian) type Index = Word16 -- | Perform a USB control request that does not transfer data. -- -- Exceptions: -- -- control :: DeviceHandle -> ControlAction (Timeout -> IO ()) -- | Perform a USB control read. -- -- Exceptions: -- -- readControl :: DeviceHandle -> ControlAction ReadAction -- | A convenience function similar to readControl which checks if -- the specified number of bytes to read were actually read. Throws an -- incompleteReadException if this is not the case. readControlExact :: DeviceHandle -> ControlAction ReadExactAction -- | Perform a USB control write. -- -- Exceptions: -- -- writeControl :: DeviceHandle -> ControlAction WriteAction -- | A convenience function similar to writeControl which checks if -- the given bytes were actually fully written. Throws an -- incompleteWriteException if this is not the case. writeControlExact :: DeviceHandle -> ControlAction WriteExactAction -- | Perform a USB bulk read. -- -- Exceptions: -- -- readBulk :: DeviceHandle -> EndpointAddress -> ReadAction -- | Perform a USB bulk write. -- -- Exceptions: -- -- writeBulk :: DeviceHandle -> EndpointAddress -> WriteAction -- | Perform a USB interrupt read. -- -- Exceptions: -- -- readInterrupt :: DeviceHandle -> EndpointAddress -> ReadAction -- | Perform a USB interrupt write. -- -- Exceptions: -- -- writeInterrupt :: DeviceHandle -> EndpointAddress -> WriteAction -- | Perform a USB isochronous read. -- -- WARNING: You need to enable the threaded runtime -- (-threaded) for this function to work correctly. It throws a -- runtime error otherwise! -- -- Exceptions: -- -- readIsochronous :: DeviceHandle -> EndpointAddress -> [Size] -> Timeout -> IO [ByteString] -- | Perform a USB isochronous write. -- -- WARNING: You need to enable the threaded runtime -- (-threaded) for this function to work correctly. It throws a -- runtime error otherwise! -- -- Exceptions: -- -- writeIsochronous :: DeviceHandle -> EndpointAddress -> [ByteString] -> Timeout -> IO [Size] module System.USB.Exceptions -- | Type of USB exceptions. data USBException -- | Input/output exception. IOException :: String -> USBException -- | Invalid parameter. InvalidParamException :: USBException -- | Access denied (insufficient permissions). It may help to run your -- program with elevated privileges or change the permissions of your -- device using something like udev. AccessException :: USBException -- | No such device (it may have been disconnected). NoDeviceException :: USBException -- | Entity not found. NotFoundException :: USBException -- | Resource busy. BusyException :: USBException -- | Operation timed out. TimeoutException :: USBException -- | If the device offered to much data. See Packets and overflows -- in the libusb documentation: -- http://libusb.sourceforge.net/api-1.0/packetoverflow.html OverflowException :: USBException -- | Pipe exception. PipeException :: USBException -- | System call interrupted (perhaps due to signal). InterruptedException :: USBException -- | Insufficient memory. NoMemException :: USBException -- | Operation not supported or unimplemented on this platform. NotSupportedException :: USBException -- | Other exception. OtherException :: USBException -- | A general IOException. ioException :: USBException -- | IOException that is thrown when the number of bytes read -- doesn't equal the requested number. incompleteReadException :: USBException -- | IOException that is thrown when the number of bytes -- written doesn't equal the requested number. incompleteWriteException :: USBException -- | A convenience module which re-exports all the important modules. module System.USB -- | This module is not intended for end users. It provides internal and -- unsafe functions used for extending this package. module System.USB.Internal -- | Handy type synonym for the libusb transfer functions. type C'TransferFunc = Ptr C'libusb_device_handle -> CUChar -> Ptr CUChar -> CInt -> Ptr CInt -> CUInt -> IO CInt withDevHndlPtr :: DeviceHandle -> (Ptr C'libusb_device_handle -> IO α) -> IO α -- | Convert a C'libusb_error to a USBException. If the -- C'libusb_error is unknown an error is thrown. convertUSBException :: (Num α, Eq α, Show α) => α -> USBException -- | Unmarshal a a 16bit word as a release number. The 16bit word should be -- encoded as a Binary Coded Decimal using 4 bits for each of the 4 -- decimals. Also see: -- -- http://en.wikipedia.org/wiki/Binary-coded_decimal unmarshalReleaseNumber :: Word16 -> ReleaseNumber -- | Unmarshal an 8bit word to a string descriptor index. 0 denotes that a -- string descriptor is not available and unmarshals to Nothing. unmarshalStrIx :: Word8 -> Maybe StrIx -- | Marshal an endpoint address so that it can be used by the -- libusb transfer functions. marshalEndpointAddress :: (Bits α, Num α) => EndpointAddress -> α -- | Unmarshal an 8bit word as an endpoint address. This function is -- primarily used when unmarshalling USB descriptors. unmarshalEndpointAddress :: Word8 -> EndpointAddress type C'TransferType = CUChar -- | Checks if the system supports asynchronous I/O. -- -- getWait :: DeviceHandle -> Maybe Wait -- | A function to wait for the termination of a submitted transfer. type Wait = Timeout -> Lock -> Ptr C'libusb_transfer -> IO () -- | Allocate a transfer with the given number of isochronous packets and -- apply the function to the resulting pointer. The transfer is -- automatically freed when the function terminates (whether normally or -- by raising an exception). -- -- A NoMemException may be thrown. allocaTransfer :: Int -> (Ptr C'libusb_transfer -> IO α) -> IO α -- | Create a FunPtr to the given transfer callback function and -- pass it to the continuation function. The FunPtr is -- automatically freed when the continuation terminates (whether normally -- or by raising an exception). withCallback :: (Ptr C'libusb_transfer -> IO ()) -> (C'libusb_transfer_cb_fn -> IO α) -> IO α -- | Strict pair of sum and length. data SumLength SumLength :: !Int -> !Int -> SumLength -- | Simultaneously calculate the sum and length of the given list. sumLength :: [Int] -> SumLength -- | Retrieve the isochronous packet descriptors from the given transfer. peekIsoPacketDescs :: Int -> Ptr C'libusb_transfer -> IO [C'libusb_iso_packet_descriptor] -- | An isochronous packet descriptor with all fields zero except for the -- length. initIsoPacketDesc :: Size -> C'libusb_iso_packet_descriptor -- | A lock is in one of two states: "locked" or "unlocked". data Lock -- | Create a lock in the "unlocked" state. newLock :: IO Lock -- | Acquires the Lock. Blocks if another thread has acquired the -- Lock. -- -- acquire behaves as follows: -- -- acquire :: Lock -> IO () -- | release changes the state to "unlocked" and returns -- immediately. -- -- The behaviour is undefined when a lock in the "unlocked" state is -- released! -- -- If there are any threads blocked on acquire the thread that -- first called acquire will be woken up. release :: Lock -> IO () -- | This module provides functions for performing standard device -- requests. The functions are primarily used for testing USB devices. -- -- To avoid name clashes with functions from System.USB it is -- advised to use an explicit import list or a qualified import. module System.USB.IO.StandardDeviceRequests -- | See: USB 2.0 Spec. section 9.4.9 setHalt :: DeviceHandle -> EndpointAddress -> (Timeout -> IO ()) -- | See: USB 2.0 Spec. section 9.4.7 -- -- This function is for testing purposes only! -- -- You should normally use -- System.USB.DeviceHandling.setConfig because that -- function notifies the underlying operating system about the changed -- configuration. setConfig :: DeviceHandle -> Maybe ConfigValue -> (Timeout -> IO ()) -- | See: USB 2.0 Spec. section 9.4.2 -- -- This function is for testing purposes only! -- -- You should normally use -- System.USB.DeviceHandling.getConfig because that -- functon may exploit operating system caches (no I/O involved). getConfig :: DeviceHandle -> (Timeout -> IO (Maybe ConfigValue)) -- | See: USB 2.0 Spec. section 9.4.1 clearRemoteWakeup :: DeviceHandle -> (Timeout -> IO ()) -- | See: USB 2.0 Spec. section 9.4.9 setRemoteWakeup :: DeviceHandle -> (Timeout -> IO ()) -- | See: USB 2.0 Spec. section 9.4.9 TODO: What about vendor-specific test -- modes? setStandardTestMode :: DeviceHandle -> TestMode -> (Timeout -> IO ()) -- | See: USB 2.0 Spec. table 9-7 data TestMode Test_J :: TestMode Test_K :: TestMode Test_SE0_NAK :: TestMode Test_Packet :: TestMode Test_Force_Enable :: TestMode -- | See: USB 2.0 Spec. section 9.4.4 getInterfaceAltSetting :: DeviceHandle -> InterfaceNumber -> (Timeout -> IO InterfaceAltSetting) -- | See: USB 2.0 Spec. section 9.4.5 getDeviceStatus :: DeviceHandle -> (Timeout -> IO DeviceStatus) -- | See: USB 2.0 Spec. section 9.4.5 getEndpointStatus :: DeviceHandle -> EndpointAddress -> (Timeout -> IO Bool) -- | See: USB 2.0 Spec. section 9.4.6 setDeviceAddress :: DeviceHandle -> Word16 -> (Timeout -> IO ()) -- | This request is used to set and then report an endpoint's -- synchronization frame. -- -- When an endpoint supports isochronous transfers, the endpoint may also -- require per-frame transfers to vary in size according to a specific -- pattern. The host and the endpoint must agree on which frame the -- repeating pattern begins. The number of the frame in which the pattern -- began is returned to the host. -- -- If a high-speed device supports the Synch Frame request, it must -- internally synchronize itself to the zeroth microframe and have a time -- notion of classic frame. Only the frame number is used to synchronize -- and reported by the device endpoint (i.e., no microframe number). The -- endpoint must synchronize to the zeroth microframe. -- -- This value is only used for isochronous data transfers using implicit -- pattern synchronization. If the specified endpoint does not support -- this request, then the device will respond with a Request Error. -- -- See: USB 2.0 Spec. section 9.4.11 synchFrame :: DeviceHandle -> EndpointAddress -> (Timeout -> IO FrameNumber) type FrameNumber = Word16 instance Typeable TestMode instance Eq TestMode instance Show TestMode instance Read TestMode instance Enum TestMode instance Data TestMode