Copyright | (c) 2009–2014 Bas van Dijk |
---|---|
License | BSD3 (see the file LICENSE) |
Maintainer | Bas van Dijk <v.dijk.bas@gmail.com> |
Safe Haskell | Trustworthy |
Language | Haskell98 |
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!
- type ReadAction = Size -> Timeout -> IO (ByteString, Status)
- type ReadExactAction = Size -> Timeout -> IO ByteString
- type WriteAction = ByteString -> Timeout -> IO (Size, Status)
- type WriteExactAction = ByteString -> Timeout -> IO ()
- type Size = Int
- type Timeout = Int
- noTimeout :: Timeout
- data Status
- data ControlSetup = ControlSetup {}
- data RequestType
- data Recipient
- type Request = Word8
- type Value = Word16
- type Index = Word16
- control :: DeviceHandle -> ControlSetup -> Timeout -> IO ()
- readControl :: DeviceHandle -> ControlSetup -> ReadAction
- readControlExact :: DeviceHandle -> ControlSetup -> ReadExactAction
- writeControl :: DeviceHandle -> ControlSetup -> WriteAction
- writeControlExact :: DeviceHandle -> ControlSetup -> WriteExactAction
- readBulk :: DeviceHandle -> EndpointAddress -> ReadAction
- writeBulk :: DeviceHandle -> EndpointAddress -> WriteAction
- readInterrupt :: DeviceHandle -> EndpointAddress -> ReadAction
- writeInterrupt :: DeviceHandle -> EndpointAddress -> WriteAction
- readIsochronous :: DeviceHandle -> EndpointAddress -> Vector Size -> Timeout -> IO (Vector ByteString)
- writeIsochronous :: DeviceHandle -> EndpointAddress -> Vector ByteString -> Timeout -> IO (Vector Size)
One-off transfers
type ReadAction = Size -> Timeout -> IO (ByteString, Status) Source #
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 ReadExactAction = Size -> Timeout -> IO ByteString Source #
Handy type synonym for read transfers that must exactly read the specified
number of bytes. An incompleteReadException
is thrown otherwise.
type WriteAction = ByteString -> Timeout -> IO (Size, Status) Source #
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 WriteExactAction = ByteString -> Timeout -> IO () Source #
Handy type synonym for write transfers that must exactly write all the
given bytes. An incompleteWriteException
is thrown otherwise.
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.
Status of a terminated transfer.
Control transfers
data ControlSetup Source #
Setup for control transfers.
ControlSetup | |
|
data RequestType Source #
The type of control requests.
Standard | Standard requests are common to all USB device's. |
Class | Class requests are common to classes of drivers. For example, all device's conforming to the HID class will have a common set of class specific requests. These will differ to a device conforming to the communications class and differ again to that of a device conforming to the mass storage class. |
Vendor | These are requests which the USB device designer (you?) can assign. These are normally different from device to device, but this is all up to your implementation and imagination. |
A common request can be directed to different recipients and based on the
recipient perform different functions. A GetStatus
Standard
request for
example, can be directed at the device, interface or endpoint. When directed
to a device it returns flags indicating the status of remote wakeup and if
the device is self powered. However if the same request is directed at the
interface it always returns zero, or should it be directed at an endpoint
will return the halt flag for the endpoint.
ToDevice | Directed to the device. |
ToInterface | Directed to the interface. |
ToEndpoint | Directed to the endpoint. |
ToOther | Directed to something other than the device, interface or endpoint. |
A potential additional parameter for the request. Usually used as an index or offset.
(Host-endian)
control :: DeviceHandle -> ControlSetup -> Timeout -> IO () Source #
Perform a USB control request that does not transfer data.
Exceptions:
TimeoutException
if the transfer timed out.PipeException
if the control request was not supported by the deviceNoDeviceException
if the device has been disconnected.- Another
USBException
.
readControl :: DeviceHandle -> ControlSetup -> ReadAction Source #
Perform a USB control read.
Exceptions:
PipeException
if the control request was not supported by the deviceNoDeviceException
if the device has been disconnected.- Another
USBException
.
readControlExact :: DeviceHandle -> ControlSetup -> ReadExactAction Source #
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.
writeControl :: DeviceHandle -> ControlSetup -> WriteAction Source #
Perform a USB control write.
Exceptions:
PipeException
if the control request was not supported by the deviceNoDeviceException
if the device has been disconnected.- Another
USBException
.
writeControlExact :: DeviceHandle -> ControlSetup -> WriteExactAction Source #
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.
Bulk transfers
:: DeviceHandle | |
-> EndpointAddress | Make sure |
-> ReadAction |
Perform a USB bulk read.
Exceptions:
PipeException
if the endpoint halted.OverflowException
if the device offered more data, see Packets and overflows in thelibusb
documentation.NoDeviceException
if the device has been disconnected.- Another
USBException
.
:: DeviceHandle | |
-> EndpointAddress | Make sure |
-> WriteAction |
Perform a USB bulk write.
Exceptions:
PipeException
if the endpoint halted.OverflowException
if the device offered more data, see Packets and overflows in thelibusb
documentation.NoDeviceException
if the device has been disconnected.- Another
USBException
.
Interrupt transfers
:: DeviceHandle | |
-> EndpointAddress | Make sure |
-> ReadAction |
Perform a USB interrupt read.
Exceptions:
PipeException
if the endpoint halted.OverflowException
if the device offered more data, see Packets and overflows in thelibusb
documentation.NoDeviceException
if the device has been disconnected.- Another
USBException
.
:: DeviceHandle | |
-> EndpointAddress | Make sure |
-> WriteAction |
Perform a USB interrupt write.
Exceptions:
PipeException
if the endpoint halted.OverflowException
if the device offered more data, see Packets and overflows in thelibusb
documentation.NoDeviceException
if the device has been disconnected.- Another
USBException
.
Isochronous transfers
WARNING: You need to enable the threaded runtime (-threaded
) when using
the isochronous functions. They throw a runtime error otherwise!
:: DeviceHandle | |
-> EndpointAddress | Make sure |
-> Vector Size | Sizes of isochronous packets to read. |
-> Timeout | |
-> IO (Vector ByteString) |
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:
PipeException
if the endpoint halted.OverflowException
if the device offered more data, see Packets and overflows in thelibusb
documentation.NoDeviceException
if the device has been disconnected.- Another
USBException
.
:: DeviceHandle | |
-> EndpointAddress | Make sure |
-> Vector ByteString | Isochronous packets to write. |
-> Timeout | |
-> IO (Vector Size) |
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:
PipeException
if the endpoint halted.OverflowException
if the device offered more data, see Packets and overflows in thelibusb
documentation.NoDeviceException
if the device has been disconnected.- Another
USBException
.