-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Communicate with USB devices -- -- This library allows 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.*. -- -- 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 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-enumerator package which -- provides iteratee enumerators for enumerating bulk and interrupt -- endpoints: -- -- http://hackage.haskell.org/package/usb-enumerator -- -- Besides this API documentation the following sources might be -- interesting: -- -- @package usb @version 0.7 -- | This module is not intended for end users. It provides internal and -- unsafe functions used for extending this package. It is primarily used -- by the usb-enumerator package. module System.USB.Unsafe -- | 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 -- | Retrieve the pointer to the libusb device handle. getDevHndlPtr :: DeviceHandle -> (Ptr C'libusb_device_handle) -- | Marshal an EndpointAddress so that it can be used by the -- libusb transfer functions. marshalEndpointAddress :: (Bits a, Num a) => EndpointAddress -> a -- | Convert a C'libusb_error to a USBException. If the -- C'libusb_error is unknown an error is thrown. convertUSBException :: Num α => α -> USBException module System.USB.Exceptions -- | Type of USB exceptions. data USBException -- | Input/output exception. IOException :: String -> USBException -- | Invalid parameter. InvalidParamException :: USBException -- | Access denied (insufficient permissions). 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 -- | Overflow. 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 -- | This module provides functionality for performing control, bulk and -- interrupt transfers. module System.USB.IO.Synchronous -- | 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 -- flag which indicates whether a transfer timed out. type ReadAction = Size -> Timeout -> IO (ByteString, TimedOut) -- | 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 an flag which indicates whether a -- transfer timed out. type WriteAction = ByteString -> Timeout -> IO (Size, TimedOut) -- | A timeout in milliseconds. A timeout defines how long a transfer -- should wait before giving up due to no response being received. For no -- timeout, use value 0. type Timeout = Int -- | True when a transfer timed out and False otherwise. type TimedOut = Bool -- | Number of bytes transferred. type Size = Int -- | 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 -- IOException if this is not the case. readControlExact :: DeviceHandle -> ControlAction (Size -> Timeout -> IO ByteString) -- | Perform a USB control write. -- -- Exceptions: -- -- writeControl :: DeviceHandle -> ControlAction WriteAction -- | 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 -- | 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 data Synchronization NoSynchronization :: Synchronization Asynchronous :: Synchronization Adaptive :: Synchronization Synchronous :: Synchronization data Usage Data :: Usage Feedback :: Usage Implicit :: Usage data MaxPacketSize MaxPacketSize :: !Size -> !TransactionOpportunities -> MaxPacketSize maxPacketSize :: MaxPacketSize -> !Size transactionOpportunities :: MaxPacketSize -> !TransactionOpportunities -- | Number of additional transactions. data TransactionOpportunities Zero :: TransactionOpportunities One :: TransactionOpportunities Two :: TransactionOpportunities -- | 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 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. getStrDesc :: DeviceHandle -> StrIx -> LangId -> Int -> IO String -- | 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. getStrDescFirstLang :: DeviceHandle -> StrIx -> Int -> IO String -- | 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 α -- | 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 -- | 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. -- -- Note that equality on devices is defined by comparing their -- descriptors: (==) = (==) `on` 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 -- | 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. newCtx :: 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 -- | A convenience module which re-exports all the important modules. module System.USB