-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A library for building tftp servers
--   
--   A library for building tftp servers
@package tftp
@version 0.2


-- | Common types used internally. Re-exports the <a>ByteString</a> type to
--   use as well as some monad transformer stuff, exceptions, logging,
--   <a>Word</a> and printf.
module Network.TFTP.Types

-- | Alias for the Lazy ByteString that is used internally
type ByteString = ByteString

-- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>.
pack :: [Word8] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'.
unpack :: ByteString -> [Word8]

-- | Candy for ByteString.pack to not interfere with Prelude(drop)
bdrop :: Int64 -> ByteString -> ByteString

-- | Candy for ByteString.take
btake :: Int64 -> ByteString -> ByteString

-- | Candy for ByteString.length
blength :: ByteString -> Int64

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>. The Handle
--   will be held open until EOF is encountered.
readFile :: FilePath -> IO ByteString

-- | Type class for monads that can send/receive messages
class (Eq address, Show address, Monad m, MonadIO m) => MessageIO m address | m -> address
sendTo :: MessageIO m address => address -> ByteString -> m Bool
receiveFrom :: MessageIO m address => Maybe Int -> m (Maybe (address, ByteString))
localAddress :: MessageIO m address => m address


-- | Buffered UDP IO utility module.
module Network.TFTP.UDPIO

-- | A monad for UDP IO
newtype UDPIO a
UDPIO :: StateT UDPIOSt IO a -> UDPIO a
runUDPIO :: UDPIO a -> StateT UDPIOSt IO a

-- | Network address of a UDP sender/receiver
type Address = SockAddr

-- | Execute an action on a bound UDP port providing access to UDP IO via
--   two functions that read and write data to/from UDP sockets. When the
--   action returns, the socket is closed.
udpIO :: Maybe String -> Maybe String -> UDPIO a -> IO a
instance Functor UDPIO
instance Monad UDPIO
instance MonadIO UDPIO
instance MonadState UDPIOSt UDPIO
instance Applicative UDPIO
instance MessageIO UDPIO Address


-- | Encapsulates parsing and generation of TFTP Messages
module Network.TFTP.Message

-- | TFTP message type.
data Message

-- | Read request
RRQ :: String -> Mode -> Message

-- | Write request
WRQ :: String -> Mode -> Message

-- | Data block with a raw bytestring
DATA :: BlockNumber -> ByteString -> Message

-- | Acknowledge message
ACK :: BlockNumber -> Message

-- | Error message
Error :: TFTPError -> Message

-- | The data mode to encode the data with
data Mode

-- | <a>netascii</a> mode
NetASCII :: Mode

-- | <a>octet</a> mode
Octet :: Mode

-- | The error codes as defined in the RFC 1350
data TFTPError

-- | Encapsulates a custom message for a non-standard error
ErrorMessage :: String -> TFTPError
FileNotFound :: TFTPError
AccessViolation :: TFTPError
DiskFull :: TFTPError
IllegalTFTPOperation :: TFTPError
UnknownTransferID :: TFTPError
FileAlreadyExists :: TFTPError
NoSuchUser :: TFTPError

-- | Decode a value from a lazy ByteString, reconstructing the original
--   structure.
decode :: Binary a => ByteString -> a

-- | Encode a value using binary serialisation to a lazy ByteString.
encode :: Binary a => a -> ByteString

-- | Convert a <a>ByteString</a> encoded in <tt>fromMode</tt> to a
--   <a>ByteString</a> encoded in <tt>toMode</tt>.
convertMode :: Mode -> Mode -> ByteString -> ByteString
instance Read Mode
instance Show Mode
instance Ord Mode
instance Eq Mode
instance Read TFTPError
instance Show TFTPError
instance Ord TFTPError
instance Eq TFTPError
instance Read Message
instance Show Message
instance Ord Message
instance Eq Message
instance Binary NString
instance Show NString
instance Binary DataChunk
instance Binary TFTPError
instance Binary Mode
instance Binary Message


-- | Transmission of data via TFTP. This implements the stop-and-wait style
--   data transmission protocol.
module Network.TFTP.Protocol

-- | XFer monad parameterised over a (MessageIO) monad.
type XFerT m address a = StateT (XFerState address) m a

-- | Execute a transfer action.
runTFTP :: MessageIO m address => XFerT m address result -> m result

-- | A simple server action that will wait for a RRQ for its file.
offerSingleFile :: MessageIO m address => Maybe Int -> String -> ByteString -> XFerT m address Bool

-- | A transfer action that sends a large chunk of data via TFTP DATA
--   messages to a destination.
writeData :: MessageIO m address => ByteString -> XFerT m address Bool

-- | Receive the next message from the client, if the client anserws with
--   the correct ack call <tt>success</tt>. If there was a timeout or the
--   ack was for an invalid index call <tt>retry</tt>, if an error occured
--   call 'error
continueAfterACK :: MessageIO m address => StateT (XFerState address) m b -> StateT (XFerState address) m b -> StateT (XFerState address) m b -> StateT (XFerState address) m b

-- | The default number of re-transmits during <a>writeData</a>
maxRetries :: Int

-- | The default time <a>continueAfterACK</a> waits for an ACK.
ackTimeOut :: Maybe Int

-- | Internal state record for a transfer
data XFerState address
XFerState :: Word16 -> Maybe address -> XFerState address

-- | The block index of an ongoing transfer
xsBlockIndex :: XFerState address -> Word16

-- | Origin of the last message received
xsFrom :: XFerState address -> Maybe address

-- | Reset the current block index for an ongoing transfer to 0
resetBlockIndex :: Monad m => XFerT m address ()

-- | Read the current block index for an ongoing transfer
getBlockIndex :: Monad m => XFerT m address Word16

-- | Increment the current block index for an ongoing transfer
incBlockIndex :: Monad m => XFerT m address Word16

-- | Return the origin(<tt>Address</tt>) of the message last received, or
--   <a>Nothing</a>
getLastPeer :: Monad m => XFerT m address (Maybe address)

-- | Overwrite the origin(<tt>Address</tt>) of the message last received
setLastPeer :: MessageIO m address => Maybe address -> XFerT m address ()

-- | Send a <a>DATA</a> packet to the origin(<tt>Address</tt>) of the
--   message last received with the current block index
replyData :: MessageIO m address => ByteString -> XFerT m address ()

-- | Send any <a>Message</a> to the address to where the last message
--   received from
reply :: MessageIO m address => Message -> XFerT m address ()

-- | Send any <a>Message</a> to an <tt>Address</tt>
send :: MessageIO m address => address -> Message -> XFerT m address ()

-- | receive a message and remeber the sender for <a>getLastPeer</a>
receive :: MessageIO m address => Maybe Int -> XFerT m address (Maybe Message)

-- | Log debug message
printInfo :: MessageIO m address => String -> XFerT m address ()

-- | Log warning message
printWarn :: MessageIO m address => String -> XFerT m address ()

-- | Log error message
printErr :: MessageIO m address => String -> XFerT m address ()

-- | Log message with custom priority
logWith :: MessageIO m address => (String -> String -> IO ()) -> String -> XFerT m address ()


-- | High-level API for building simple TFTP Servers, currently restricted
--   to answering read requests.
module Network.TFTP.Server

-- | Create a simple server that answers a single read request from a
--   single client for a file, and return <a>Nothing</a> when the transfer
--   was successfully completed, or 'Just <a>message</a>'
singleBinary :: Maybe Int -> FilePath -> String -> Maybe String -> Maybe String -> IO (Maybe String)