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


-- | Simple network sockets usage patterns.
--   
--   Simple network sockets usage patterns.
--   
--   See the <tt>NEWS</tt> file in the source distribution to learn about
--   any important changes between version.
@package network-simple
@version 0.2.1.0


-- | This module exports functions that abstract simple TCP <a>Socket</a>
--   usage patterns.
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 the <a>sClose</a> function from
--   <a>Network.Socket</a> instead.
connect :: HostName -> ServiceName -> ((Socket, SockAddr) -> IO r) -> IO 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 :: HostPreference -> ServiceName -> ((Socket, SockAddr) -> IO ()) -> IO ()

-- | 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 the <a>listen</a> and <a>sClose</a> functions 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 :: HostPreference -> ServiceName -> ((Socket, SockAddr) -> IO r) -> IO r

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

-- | 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 :: Socket -> ((Socket, SockAddr) -> IO ()) -> IO 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 :: Socket -> Int -> IO (Maybe ByteString)

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

-- | 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>sClose</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 :: HostPreference -> ServiceName -> IO (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>sClose</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 :: HostName -> ServiceName -> IO (Socket, SockAddr)

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