HB.O      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMN#Bas van Dijk <v.dijk.bas@gmail.com>d0Control transfers can have three request types: Standard, Class and Vendor. We disallow Standard, requests however because with them you can 9destroy the safety guarantees that this module provides. OPDHandy type synonym that names the parameters of a control transfer. 2Class of transfer types that support enumeration. An enumerator for an  endpoint  with either a  or  transfer type. +Chunk size. A good value for this would be  the Q . R. -Timeout (in milliseconds) that this function / should wait for each chunk before giving up . due to no response being received. For no  timeout, use value 0. -Class of transfer types that support writing Write bytes to an  endpoint  with either a  or  transfer type.  Exceptions:  S if the endpoint halted.  T& if the device has been disconnected.  Another U. (Handy type synonym for write transfers. A  WriteAction9 is a function which takes the bytestring to write and a Qtimeout. The function returns an action which, when exectued, returns the number Nof bytes that were actually written paired with an indication if the transfer  timed out. .Class of transfer types that support reading. Read bytes from an  endpoint  with either a  or  transfer type.  Exceptions:  S if the endpoint halted.  V" if the device offered more data,  see Packets and overflows in the libusb documentation:   9http://libusb.sourceforge.net/api-1.0/packetoverflow.html.  T& if the device has been disconnected.  Another U. 'Handy type synonym for read transfers. A  ReadActionB is a function which takes a size which defines how many bytes to Iread and a timeout. The function returns an action which, when executed, Qperforms the actual read and returns the bytestring that was read paired with an &indication if the transfer timed out. 7An overloaded constructor function for transfer types. <An overloaded constructor function for transfer directions. 9In transfer direction (device -> host) used for reading. :Out transfer direction (host -> device) used for writing. I/CO operations on endpoints are type-safe. You can only read from an endpoint with an : transfer direction and you can only write to an endpoint with an  transfer direction. JReading and writing also have different implementations for the different endpoint transfer types like:  and . I/O with endpoints of other transfer types like  and  is not possible. LThis type lifts the transfer direction and transfer type information to the type-level so that I/O operations like   and  can &specify which endpoints they support. 5You can retrieve the endpoints of an alternate using =. W(A handle to a setted alternate setting. 'You get a handle to an alternate using :, ; or <. The type variable sAlt is used to ensure that you can'+t return this handle from these functions. X  A supported " alternate setting  which you can retrieve using 9. Y!*A regional handle to a claimed interface. 8A regional handle to a claimed interface can be created  by applying 6 or 7% to the interface you wish to claim. Z")A supported interface of a configuration which you can retrieve using 5. To retrieve the [! descriptors of an interface use *. \# This exception can be thrown in 3 to indicate that the $device is currently not configured. $%!This exception can be thrown in:  0  2 or 4  : or < Cto indicate that the device was already configured with a setting. &'A handle to an active ( which you can get using: 2, 3 or 4. The type variable sCfg is used to ensure that you can'+t return this handle from these functions. ](*A supported configuration of a USB device parameterized by the region r in which it was created. QNote that, just like a regional device handle, a configuration can be duplicated to a parent region using ^. ?Also note that you can get the descriptor of the configuration  by applying * to it. _)**Get the descriptor of a given USB entity. ++A regional handle to an opened USB device. EA regional handle to an opened USB device can be created by applying , or -% to the USB device you wish to open. Note that you can also  duplicate& a regional device handle by applying ^ to it. `,3Open a device and obtain a regional device handle. ?The device is automatically closed when the region terminates. DThis is a non-blocking function; no requests are sent over the bus.  Exceptions:  a* if there is a memory allocation failure.  b+ if the user has insufficient permissions.  T& if the device has been disconnected.  Another U. -LConvenience function which opens the device, applies the given continuation Pfunction to the resulting regional device handle and runs the resulting region. .IConvenience function which finds the first device attached to the system Nwhich satisfies the given predicate on its descriptor, then opens that device Land applies the given continuation function to the resulting device handle.  Exceptions:  c< if no device is found which satisfies the given predicate.  a* if there is a memory allocation failure.  b+ if the user has insufficient permissions.  T& if the device has been disconnected.  Another U. $Predicate on the device descriptor. Continuation function dFInternally used function which searches through the given list of USB J entities (like Devices, Configs, Interfaces or Alternates) for the first M entity which satisfies the given predicate on its descriptor. Then opens or L sets that entity by applying the given open or set function to the entity. With Predicate on descriptor Continuation function eIInternally used function for getting the actual USB device handle from a  regional device handle. /OConvenience function for retrieving the device from the given regional handle. 03Perform a USB port reset to reinitialize a device. >The system will attempt to restore the previous configuration 6and alternate settings after the reset has completed. Note the constraint: pr `AncestorRegion` cr". This allows this function to be executed in any child region cr of the parent region pr in which the given regional handle was created. <You can only reset a device when all computations passed to 2, 3 and 4# have been terminated. If you call  resetDevice+ and such a computation is still running a &% exception is thrown. LIf the reset fails, the descriptors change, or the previous state cannot be Prestored, the device will appear to be disconnected and reconnected. This means Othat the device handle is no longer valid (you should close it) and rediscover the device. A c. is raised to indicate that this is the case. OTODO: Think about how to handle the implications of the the previous paragraph! EThis is a blocking function which usually incurs a noticeable delay.  Exceptions:  &%' if a configuration has been set using 2,  3 and 4.  c* if re-enumeration is required, or if the ! device has been disconnected.  Another U. 1FRetrieve the supported configurations from the given regional handle. @Note that the configuration is parameterized by the same region r in which the Lregional handle was created. This ensures you can never use a configuration outside that region. fJInternally used function for getting all the configuration descriptors of  the given device. 23Set the active configuration for a device and then Mapply the given continuation function to the resulting configuration handle. OUSB devices support multiple configurations of which only one can be active at 2any given time. When a configuration is set using 2, 3 or 4> no threads may set a new configuration until the computation Bpassed to these functions terminates. If you do try to set one, a &% exception will be thrown. PThe operating system may or may not have already set an active configuration on Pthe device. It is up to your application to ensure the correct configuration is Qselected before you attempt to claim interfaces and perform other operations. If 2you want to use the current active configuration: 3. KIf you call this function on a device already configured with the selected Mconfiguration, then this function will act as a lightweight device reset: it  will issue a SET_CONFIGURATION2 request using the current configuration, causing Nmost 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:  &%/ if a configuration has already been set using  2, 3 or 4.  g& if interfaces are currently claimed.  T% if the device has been disconnected  Another U. #The configuration you wish to set. Continuation function. h(Internally used function which throws a &% exception if  the given MVar was set. If the given MVar wasn't set it will be set M before the given computation is performed. When the computation terminates, 1 wheter normally or by raising an exception, the MVar will be unset again. i(Internally used function which sets the MVar before the computation is N performed. When the computation terminates, wheter normally or by raising an  exception, the MVar will be unset again. j;Internally used function which overwrites the value in the MVar. KNote that because this function is used in a context in which asynchronous $ exceptions are already masked I don'"t mask them again. So be carefull 0 when using this function in any other context! 3IApply the given continuation function to the configuration handle of the 9current active configuration of the given device handle. HThis function needs to determine the current active configuration. This <information may be cached by the operating system. If it isn't cached this Jfunction will block while a control transfer is submitted to retrieve the  information.  Exceptions:  $#" if the device is not configured.  T& if the device has been disconnected.  Another U. Regional handle to the device " from which you want to use the  active configuration. Continuation function 4<Convenience function which finds the first configuration of Othe given device handle which satisfies the given predicate on its descriptor, Mthen sets that configuration and applies the given function to the resulting configuration handle. This function calls 2 so do see its documentation.  Exceptions:  &%/ if a configuration has already been set using  2, 3 or 4.  c7 if no configuration is found that satisfies the given  predicate.  g& if interfaces are currently claimed.  T% if the device has been disconnected  Another U. "Regional handle to the device for  which you want to set a  configuration. Predicate on the configuration  descriptor. Continuation function. 5ARetrieve the supported interfaces from the configuration handle. 0Note that the interface is parameterized by the sCfg of the configuration Ohandle it is derived from. This ensures that it can never be returned from the 2functions that created this configuration handle: 2, 3 and 4. NThe latter is useful because outside those functions the active configuration Emay change. If at that moment you still have an interface of the old -configuration claiming it would be an error. 6)Claim the given interface in the region. DWhen the region terminates the interface is released automatically. ?Note that it is allowed to claim an already-claimed interface. LClaiming of interfaces is a purely logical operation; it does not cause any Mrequests to be sent over the bus. Interface claiming is used to instruct the Nunderlying operating system that your application wishes to take ownership of the interface. !This is a non-blocking function.  Exceptions:  g9 if another program or driver has claimed the interface.  T& if the device has been disconnected.  Another U. Interface you wish to claim 7!The interface you wish to claim. Continuation function. 8BConvenience function which finds the first interface of the given Mconfiguration handle which satisfies the given predicate on its descriptors, Othen claims that interfaces and applies the given continuation function to the resulting regional handle.  Exceptions:  c? if no interface was found that satisfies the fiven predicate.  g9 if another program or driver has claimed the interface.  T& if the device has been disconnected.  Another U. #Handle to a configuration of which # you want to claim an interface. (Predicate on the interface descriptors. Continuation function. 9KRetrieve the supported alternate settings from the given interface handle. ONote that the alternate setting is parameterized by the same type variables as Jthe interface handle. This ensures you can never use an alternate setting >outside the region in which the interface handle was created. :/Activate an alternate setting for an interface Rand then apply the given continuation function to the resulting alternate handle. OSimillary to configurations, interfaces support multiple alternate settings of Owhich only one can be active at any given time. When an alternate is set using :, ; or < no threads may set a Qnew alternate until the computation passed to these functions terminates. If you do try to set one a &% exception will be thrown. IThe operating system has always set an interface in one of the available =alternates. If you want to use the current active alternate: ;. This is a blocking function.  Exceptions:  T& if the device has been disconnected.  &%, if an alternate has already been set using  :, ; or <.  Another U. The alternate you wish to set. Continuation function. ;GApply the given function to the alternate handle of the current active )alternate of the given interface handle. KTo determine the current active alternate this function will block while a ;control transfer is submitted to retrieve the information. INote that unlike configurations an interface is always set in one of the  available alternates, so unlike 3 this function will never throw an exception like $#.  Exceptions:  T& if the device has been disconnected.  Another U. Regional handle to the ! interface from which you want  to use the active alternate. Continuation function. <LConvenience function which finds the first alternate of the given interface Mhandle which satisfies the given predicate on its descriptor, then sets that Lalternate and applies the given function to the resulting alternate handle. This function calls : so do see its documentation.  Exceptions:  c3 if no alternate is found that satisfies the given  predicate.  T& if the device has been disconnected.  &%, if an alternate has already been set using  :, ; or <.  Another U. Regional handle to the  interface for which you want  to set an alternate. Predicate on the interface  descriptor. Continuation function =;Retrieve all the endpoints from the given alternate handle > which are of the given transfer direction and transfer type. Handle to the alternate from " which you want to retrieve its  endpoints.  Filter all endpoints which have  this transfer direction.  Filter all endpoints which have  this transfer type. > Similar to =. but will retrieve the endpoints based on the 8 inferred type of transfer direction and transfer type.  Note that:   getEndpoints' altHndl = = altHndl   . kl?Clear the halt/!stall condition for an endpoint. BEndpoints with halt status are unable to receive or transmit data %until the halt condition is stalled. WYou should cancel all pending transfers before attempting to clear the halt condition. This is a blocking function.  Exceptions:  T& if the device has been disconnected.  Another U. mn@Perform a USB  isochronous read. WARNING:* You need to enable the threaded runtime ( -threaded ) for this Afunction to work correctly. It throws a runtime error otherwise!  Exceptions:  S if the endpoint halted.  V" if the device offered more data,  see Packets and overflows in the libusb documentation:   9http://libusb.sourceforge.net/api-1.0/packetoverflow.html.  T& if the device has been disconnected.  Another U. Sizes of isochronous packets APerform a USB  isochronous write. WARNING:* You need to enable the threaded runtime ( -threaded ) for this Afunction to work correctly. It throws a runtime error otherwise!  Exceptions:  S if the endpoint halted.  V" if the device offered more data,  see Packets and overflows in the libusb documentation:   9http://libusb.sourceforge.net/api-1.0/packetoverflow.html.  T& if the device has been disconnected.  Another U. Sizes of isochronous packets B Iteratee enumerator for reading  isochronous endpoints. WARNING:* You need to enable the threaded runtime ( -threaded ) for this B function to work correctly. It throws a runtime error otherwise! oCPerform a USB control& request that does not transfer data.  Exceptions:  p if the transfer timed out.  S8 if the control request was not supported by the device  T& if the device has been disconnected.  Another U. DPerform a USB control read.  Exceptions:  S8 if the control request was not supported by the device  T& if the device has been disconnected.  Another U. E"A convenience function similar to D which checks if the 7 specified number of bytes to read were actually read.  Throws an q if this is not the case. FPerform a USB control write.  Exceptions:  S8 if the control request was not supported by the device  T& if the device has been disconnected.  Another U. G"A convenience function similar to F which checks if the given $ bytes were actually fully written.  Throws an incompleteWriteException if this is not the case. H(Retrieve a list of supported languages. This function may throw Us. I,Retrieve a string descriptor from a device. This function may throw Us. /TODO: The following can be made more type-safe!  When I call I4 I would like the type system to guarantee that the given StrIx and LangId actually belong to the given Handle . In other Nwords I would like to get a type error when they are some arbitrary number or come from another device. 9Maximum number of characters in the requested string. An  q# will be thrown when the requested & string is larger than this number. JORetrieve a string descriptor from a device using the first supported language. This function may throw Us. .Maximum number of characters in the requested  string. An q will be thrown when 4 the requested string is larger than this number. K8Determine if a kernel driver is active on an interface. QIf a kernel driver is active, you cannot claim the interface, and libusb will be unable to perform I/O.  Exceptions:  T& if the device has been disconnected.  Another U. L*Detach a kernel driver from an interface. IIf successful, you will then be able to claim the interface and perform I/O.  Exceptions:  c! if no kernel driver was active.  r" if the interface does not exist.  T& if the device has been disconnected.  Another U. MRe-attach an interface'&s kernel driver, which was previously detached using L.  Exceptions:  c! if no kernel driver was active.  r" if the interface does not exist.  T& if the device has been disconnected.  g8 if the driver cannot be attached because the interface & is claimed by a program or driver.  Another U. NFIf a kernel driver is active on the specified interface the driver is Pdetached and the given action is executed. If the action terminates, whether by Mnormal termination or by raising an exception, the kernel driver is attached Qagain. If a kernel driver is not active on the specified interface the action is just executed.  Exceptions:  T& if the device has been disconnected.  Another U. Zstuvw^xyz{|  !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNO+,-./)*0(1'2%&3#$4"5!678 9:;<=> ?  @ABCDEFGHIJKLMNO    !"#$$%&&'()**+,-./0123456789:;<=>?@ABCDEFGHIJKLMN}       !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMKLNKLOKLPKLQKLRKL!STU"%KLVKLWKLXYZ[KL\]^_`abcdKLeKLfKLgSThSTiSTjSTkSTlSTmSTnSToSTpSTqr usb-safe-0.13System.USB.Safe RequestTypeVendorClass ControlActionEnumReadEndpointenumReadEndpoint WriteEndpoint writeEndpoint WriteAction ReadEndpoint readEndpoint ReadActionMkTransferTypemkTransferType InterruptBulk IsochronousControl TransferTypeMkTransferDirectionmkTransferDirectionInOutTransferDirectionEndpointAlternateHandle AlternateRegionalInterfaceHandle InterfaceNoActiveConfigSettingAlreadySet ConfigHandleConfig GetDescriptorgetDescRegionalDeviceHandle openDevice withDevicewithDeviceWhich getDevice resetDevice getConfigs setConfiguseActiveConfigsetConfigWhich getInterfacesclaim withInterfacewithInterfaceWhich getAlternates setAlternateuseActiveAlternatesetAlternateWhich getEndpoints getEndpoints' clearHaltreadIsochronousEndpointwriteIsochronousEndpointenumReadIsochronousEndpointcontrol readControlreadControlExact writeControlwriteControlExact getLanguages getStrDescgetStrDescFirstLangkernelDriverActivedetachKernelDriverattachKernelDriverwithDetachedKernelDriverWriteExactActionReadExactActionusb-1.0System.USB.Base maxPacketSizeendpointMaxPacketSize PipeExceptionNoDeviceException USBExceptionOverflowException regions-0.10#Control.Monad.Trans.Region.InternaldupNoMemExceptionAccessExceptionNotFoundExceptionuseWhichgetInternalDevHndlgetConfigDescs BusyExceptionwithUnsettedMVarwithSettedMVar overwriteMVareqDireqType transferWithwrapreqTypeToInternalTimeoutException IOExceptionInvalidParamException liftCatch mapRegionT liftCallCC runRegionTRegionTDupAncestorRegion RootRegion LocalRegionLocal