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


-- | Simple network sockets usage patterns.
--   
--   This module exports functions that abstract simple network socket
--   usage patterns.
--   
--   See the <tt>changelog.md</tt> file in the source distribution to learn
--   about any important changes between version.
@package network-simple
@version 0.4


-- | This module exports functions that abstract simple TCP <a>Socket</a>
--   usage patterns.
--   
--   This module uses <a>MonadIO</a> and <a>MonadMask</a> extensively so
--   that you can reuse these functions in monads other than <a>IO</a>.
--   However, if you don't care about any of that, just pretend you are
--   using the <a>IO</a> monad all the time and everything will work as
--   expected.
module Network.Simple.TCP

-- | Connect to a TCP server and use the connection.
--   
--   The connection socket is closed when done or in case of exceptions.
--   
--   If you prefer to acquire and close the socket yourself, then use
--   <a>connectSock</a> and <a>closeSock</a>.
connect :: (MonadIO m, MonadMask m) => HostName -> ServiceName -> ((Socket, SockAddr) -> m r) -> m r

-- | Start a TCP server that accepts incoming connections and handles them
--   concurrently in different threads.
--   
--   Any acquired network resources are properly closed and discarded when
--   done or in case of exceptions.
--   
--   Note: This function performs <a>listen</a> and <a>acceptFork</a>, so
--   you don't need to perform those manually.
serve :: MonadIO m => HostPreference -> ServiceName -> ((Socket, SockAddr) -> IO ()) -> m ()

-- | Bind a TCP listening socket and use it.
--   
--   The listening socket is closed when done or in case of exceptions.
--   
--   If you prefer to acquire and close the socket yourself, then use
--   <a>bindSock</a>, <a>closeSock</a> and the <a>listen</a> function from
--   <a>Network.Socket</a> instead.
--   
--   Note: <a>maxListenQueue</a> is tipically 128, which is too small for
--   high performance servers. So, we use the maximum between
--   <a>maxListenQueue</a> and 2048 as the default size of the listening
--   queue. The <a>NoDelay</a> and <a>ReuseAddr</a> options are set on the
--   socket.
listen :: (MonadIO m, MonadMask m) => HostPreference -> ServiceName -> ((Socket, SockAddr) -> m r) -> m r

-- | Accept a single incoming connection and use it.
--   
--   The connection socket is closed when done or in case of exceptions.
accept :: (MonadIO m, MonadMask m) => Socket -> ((Socket, SockAddr) -> m r) -> m r

-- | Accept a single incoming connection and use it in a different thread.
--   
--   The connection socket is closed when done or in case of exceptions.
acceptFork :: MonadIO m => Socket -> ((Socket, SockAddr) -> IO ()) -> m ThreadId

-- | Read up to a limited number of bytes from a socket.
--   
--   Returns <a>Nothing</a> if the remote end closed the connection or
--   end-of-input was reached. The number of returned bytes might be less
--   than the specified limit.
recv :: MonadIO m => Socket -> Int -> m (Maybe ByteString)

-- | Writes the given bytes to the socket.
send :: MonadIO m => Socket -> ByteString -> m ()

-- | Obtain a <a>Socket</a> bound to the given host name and TCP service
--   port.
--   
--   The obtained <a>Socket</a> should be closed manually using
--   <a>closeSock</a> when it's not needed anymore.
--   
--   Prefer to use <a>listen</a> if you will be listening on this socket
--   and using it within a limited scope, and would like it to be closed
--   immediately after its usage or in case of exceptions.
bindSock :: MonadIO m => HostPreference -> ServiceName -> m (Socket, SockAddr)

-- | Obtain a <a>Socket</a> connected to the given host and TCP service
--   port.
--   
--   The obtained <a>Socket</a> should be closed manually using
--   <a>closeSock</a> when it's not needed anymore, otherwise you risk
--   having the socket open for much longer than needed.
--   
--   Prefer to use <a>connect</a> if you will be using the socket within a
--   limited scope and would like it to be closed immediately after its
--   usage or in case of exceptions.
connectSock :: MonadIO m => HostName -> ServiceName -> m (Socket, SockAddr)

-- | Close the <a>Socket</a>.
closeSock :: MonadIO m => Socket -> m ()

-- | On Windows operating systems, the networking subsystem has to be
--   initialised using <a>withSocketsDo</a> before any networking
--   operations can be used. eg.
--   
--   <pre>
--   main = withSocketsDo $ do {...}
--   </pre>
--   
--   Although this is only strictly necessary on Windows platforms, it is
--   harmless on other platforms, so for portability it is good practice to
--   use it all the time.
withSocketsDo :: IO a -> IO a

-- | Preferred host to bind.
data HostPreference

-- | Any available host.
HostAny :: HostPreference

-- | Any available IPv4 host.
HostIPv4 :: HostPreference

-- | Any available IPv6 host.
HostIPv6 :: HostPreference

-- | An explicit host name.
Host :: HostName -> HostPreference

-- | Either a host name e.g., <tt>"haskell.org"</tt> or a numeric host
--   address string consisting of a dotted decimal IPv4 address or an IPv6
--   address e.g., <tt>"192.168.0.1"</tt>.
type HostName = String
type ServiceName = String
data Socket :: *
data SockAddr :: *