-- 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.0.5


-- | 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 typically 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 a <a>ByteString</a> to the socket.
send :: MonadIO m => Socket -> ByteString -> m ()

-- | Writes a lazy <a>ByteString</a> to the socket.
sendLazy :: MonadIO m => Socket -> ByteString -> m ()

-- | Writes the given list of <a>ByteString</a>s to the socket. This is
--   faster than sending them individually.
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.
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 ()

-- | 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

-- | Represents a socket. The fields are, respectively:
--   
--   <ul>
--   <li>File descriptor</li>
--   <li>Socket family</li>
--   <li>Socket type</li>
--   <li>Protocol number</li>
--   <li>Status flag</li>
--   </ul>
--   
--   If you are calling the <a>MkSocket</a> constructor directly you should
--   ensure you have called <a>withSocketsDo</a> and that the file
--   descriptor is in non-blocking mode. See <a>setNonBlockIfNeeded</a>.
--   
--   <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 :: *
