System.USB.Internal

This module is not intended for end users. It provides internal and unsafe functions used for extending this package.

Documentation

type C'TransferFunc = Ptr C'libusb_device_handle -> CUChar -> Ptr CUChar -> CInt -> Ptr CInt -> CUInt -> IO CInt

Handy type synonym for the libusb transfer functions.

withDevHndlPtr :: DeviceHandle -> (Ptr C'libusb_device_handle -> IO α) -> IO α

convertUSBException :: Num α => α -> USBException

Convert a C'libusb_error to a USBException. If the C'libusb_error is unknown an error is thrown.

unmarshalReleaseNumber :: Word16 -> ReleaseNumber

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

unmarshalStrIx :: Word8 -> Maybe StrIx

Unmarshal an 8bit word to a string descriptor index. 0 denotes that a string descriptor is not available and unmarshals to Nothing.

Marshal and unmarshal endpoint addresses

The address should be encoded according to section 9.6.6 of the USB 2.0 specification.

• Bits 0-3 denote the endpointNumber.
• Bit 7 denotes the transferDirection. 0 denotes Out and 1 denotes In.

marshalEndpointAddress :: (Bits α, Num α) => EndpointAddress -> α

Marshal an endpoint address so that it can be used by the libusb transfer functions.

unmarshalEndpointAddress :: Word8 -> EndpointAddress

Unmarshal an 8bit word as an endpoint address. This function is primarily used when unmarshalling USB descriptors.

Useful types and functions for asynchronous implementations

type C'TransferType = CUChar

threaded :: Bool

True if the RTS supports bound threads and False otherwise.

The asynchronous implementations only work correctly when this is True.

allocaTransfer :: Int -> (Ptr C'libusb_transfer -> IO α) -> 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.

withCallback :: (Ptr C'libusb_transfer -> IO ()) -> (C'libusb_transfer_cb_fn -> 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).

data SumLength

Strict pair of sum and length.

Constructors

SumLength !Int !Int

sumLength :: [Int] -> SumLength

Simultaneously calculate the sum and length of the given list.

peekIsoPacketDescs :: Int -> Ptr C'libusb_transfer -> IO [C'libusb_iso_packet_descriptor]

Retrieve the isochronous packet descriptors from the given transfer.

initIsoPacketDesc :: Size -> C'libusb_iso_packet_descriptor

An isochronous packet descriptor with all fields zero except for the length.

getCtx :: Device -> Ctx

This reference to the Ctx is needed so that it won't get garbage collected. The finalizer p'libusb_exit is run only when all references to Devices are gone.

getEventManager :: Ctx -> Maybe (EventManager, Maybe (IO ()))

Retrieve the optional event manager from the context and the optional IO action for handling events.

Locks

data Lock

A lock is in one of two states: "locked" or "unlocked".

Instances

Eq Lock

newLock :: IO Lock

Create a lock in the "unlocked" state.

acquire :: Lock -> IO ()

Acquires the Lock. Blocks if another thread has acquired the Lock.

acquire behaves as follows:

• When the state is "unlocked" acquire changes the state to "locked".
• When the state is "locked" acquire blocks until a call to release in another thread wakes the calling thread. Upon awakening it will change the state to "locked".

release :: 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.