-- 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 versions.
@package network-simple
@version 0.4.2


-- | 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 shut down and 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 sockets are properly shut down and closed when done or in
--   case of exceptions. Exceptions from the threads handling the
--   individual connections won't cause <a>serve</a> to die.
--   
--   Note: This function performs <a>listen</a>, <a>acceptFork</a>, so
--   don't perform those manually.
serve :: MonadIO m => HostPreference -> ServiceName -> ((Socket, SockAddr) -> IO ()) -> m a

-- | 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> and <a>closeSock</a>, as well as <a>listenSock</a>
--   function.
--   
--   Note: The <a>NoDelay</a> and <a>ReuseAddr</a> options are set on the
--   socket. The maximum number of incoming queued connections is 2048.
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 shut down and 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 shut down and 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, but it will never <a>null</a>.
recv :: MonadIO m => Socket -> Int -> m (Maybe ByteString)

-- | Writes a <a>ByteString</a> to the socket.
--   
--   Note: On POSIX, calling <a>sendLazy</a> once is much more efficient
--   than repeatedly calling <a>send</a> on strict <a>ByteString</a>s. Use
--   <tt><a>sendLazy</a> sock . <a>fromChunks</a></tt> if you have more
--   than one strict <a>ByteString</a> to send.
send :: MonadIO m => Socket -> ByteString -> m ()

-- | Writes a lazy <a>ByteString</a> to the socket.
--   
--   Note: This uses <tt>writev(2)</tt> on POSIX.
sendLazy :: MonadIO m => Socket -> ByteString -> m ()

-- | Writes the given list of <a>ByteString</a>s to the socket.
--   
--   Note: This uses <tt>writev(2)</tt> on POSIX.

-- | <i>Deprecated: Use <tt><a>sendLazy</a> sock .
--   <a>fromChunks</a></tt></i>
sendMany :: 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.
--   
--   Note: The <a>NoDelay</a> and <a>ReuseAddr</a> options are set on the
--   socket.
bindSock :: MonadIO m => HostPreference -> ServiceName -> m (Socket, SockAddr)

-- | Listen for new connections of the given bound socket.
listenSock :: MonadIO m => Socket -> Int -> m ()

-- | 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 connection and 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)

-- | Shuts down and closes the <a>Socket</a>, silently ignoring any
--   synchronous exception that might happen.
closeSock :: MonadIO m => Socket -> m ()

-- | With older versions of the <tt>network</tt> library (version 2.6.0.2
--   or earlier) on Windows operating systems, the networking subsystem
--   must be initialised using <a>withSocketsDo</a> before any networking
--   operations can be used. eg.
--   
--   <pre>
--   main = withSocketsDo $ do {...}
--   </pre>
--   
--   It is fine to nest calls to <a>withSocketsDo</a>, and to perform
--   networking operations after <a>withSocketsDo</a> has returned.
--   
--   In newer versions of the <tt>network</tt> library (version v2.6.1.0 or
--   later) it is only necessary to call <a>withSocketsDo</a> if you are
--   calling the <a>MkSocket</a> constructor directly. However, for
--   compatibility with older versions on Windows, it is good practice to
--   always call <a>withSocketsDo</a> (it's very cheap).
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

-- | A socket data type. <a>Socket</a>s are not GCed unless they are closed
--   by <tt>close</tt>.
data Socket

-- | The existence of a constructor does not necessarily imply that that
--   socket address type is supported on your system: see
--   <a>isSupportedSockAddr</a>.
data SockAddr