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


-- | One stop solution for tcp client and server with tls support.
--   
--   One stop solution for tcp client and server with tls support.
@package tcp-streams
@version 0.6.0.0


-- | This module provides convenience functions for interfacing
--   <tt>io-streams</tt> with raw tcp. the default receive buffer size is
--   4096. sending is unbuffered, anything write into <a>OutputStream</a>
--   will be immediately send to underlying socket.
--   
--   Reading <a>InputStream</a> will block until GHC IO manager find data
--   is ready, for example 'System.IO.Streams.ByteString.readExactly 1024'
--   will block until 1024 bytes are available.
--   
--   When socket is closed, the <a>InputStream</a> will be closed
--   too(further reading will return <a>Nothing</a>), no exception will be
--   thrown. You still should handle <a>IOError</a> when you write to
--   <a>OutputStream</a> for safety, but no exception doesn't essentially
--   mean a successful write, especially under bad network
--   environment(broken wire for example).
--   
--   <tt>TCP_NODELAY</tt> are enabled by default. you can use
--   <a>setSocketOption</a> to adjust.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import qualified <a>System.IO.Streams.TCP</a> as TCP
--   </pre>
module System.IO.Streams.TCP

-- | Convenience function for initiating an raw TCP connection to the given
--   <tt>(<a>HostName</a>, <a>PortNumber</a>)</tt> combination.
--   
--   Note that sending an end-of-file to the returned <a>OutputStream</a>
--   will not close the underlying Socket connection.
connectSocket :: HostName -> PortNumber -> IO Socket

-- | Connect to remote tcp server.
--   
--   You may need to use <a>bracket</a> pattern to enusre <a>Socket</a> 's
--   safety.
connect :: HostName -> PortNumber -> IO (InputStream ByteString, OutputStream ByteString, Socket)

-- | Connect to remote tcp server with adjustable receive buffer size.
connectWithBufferSize :: HostName -> PortNumber -> Int -> IO (InputStream ByteString, OutputStream ByteString, Socket)

-- | Convenience function for initiating an TCP connection to the given
--   <tt>(<a>HostName</a>, <a>PortNumber</a>)</tt> combination. The socket
--   will be closed and deleted after the user handler runs.
withConnection :: HostName -> PortNumber -> (InputStream ByteString -> OutputStream ByteString -> Socket -> IO a) -> IO a

-- | Bind and listen on port with a limit on connection count.
bindAndListen :: PortNumber -> Int -> IO Socket

-- | Accept a new connection from remote client, return a
--   <a>InputStream</a> / <a>OutputStream</a> pair, a new underlying
--   <a>Socket</a>, and remote <a>SockAddr</a>,you should call
--   <a>bindAndListen</a> first.
--   
--   This function will block if there's no connection comming.
accept :: Socket -> IO (InputStream ByteString, OutputStream ByteString, Socket, SockAddr)

-- | accept a connection with adjustable receive buffer size.
acceptWithBufferSize :: Socket -> Int -> IO (InputStream ByteString, OutputStream ByteString, Socket, SockAddr)

-- | Convert a <a>Socket</a> into a streams pair, catch
--   <tt>IOException</tt>s on receiving and close <a>InputStream</a>. You
--   still should handle <a>IOError</a> when you write to
--   <a>OutputStream</a> for safety, but no exception doesn't essentially
--   mean a successful write, especially under bad network
--   environment(broken wire for example).
--   
--   During receiving, the status <a>MVar</a> is locked, so that a cleanup
--   thread can't affect receiving until finish.
socketToStreamsWithBufferSize :: Int -> Socket -> IO (InputStream ByteString, OutputStream ByteString)

-- | Close the socket. Sending data to or receiving data from closed socket
--   may lead to undefined behaviour.
close :: Socket -> IO ()


-- | Helpers for setting up a tls connection with <tt>tls</tt> package, for
--   further customization, please refer to <tt>tls</tt> package.
--   
--   Note, functions in this module will throw error if can't load
--   certificates or CA store.
module Data.TLSSetting

-- | The whole point of TLS is that: a peer should have already trusted
--   some certificates, which can be used for validating other peer's
--   certificates. if the certificates sent by other side form a chain. and
--   one of them is issued by one of <a>TrustedCAStore</a>, Then the peer
--   will be trusted.
data TrustedCAStore

-- | provided by your operating system.
SystemCAStore :: TrustedCAStore

-- | provided by <a>Mozilla</a>.
MozillaCAStore :: TrustedCAStore

-- | provided by your self, the CA file can contain multiple certificates.
CustomCAStore :: FilePath -> TrustedCAStore

-- | make a simple tls <a>ClientParams</a> that will validate server and
--   use tls connection without providing client's own certificate.
--   suitable for connecting server which don't validate clients.
--   
--   we defer setting of <a>clientServerIdentification</a> to connecting
--   phase.
--   
--   Note, tls's default validating method require server has v3
--   certificate. you can use openssl's V3 extension to issue such a
--   certificate. or change <a>ClientParams</a> before connecting.
makeClientParams :: TrustedCAStore -> IO ClientParams

-- | make a simple tls <a>ClientParams</a> that will validate server and
--   use tls connection while providing client's own certificate as well.
--   suitable for connecting server which validate clients.
--   
--   Also only accept v3 certificate.
makeClientParams' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO ClientParams

-- | make a simple tls <a>ServerParams</a> without validating client's
--   certificate.
makeServerParams :: FilePath -> [FilePath] -> FilePath -> IO ServerParams

-- | make a tls <a>ServerParams</a> that also validating client's
--   certificate.
makeServerParams' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO ServerParams

-- | Get the built-in mozilla CA's path.
mozillaCAStorePath :: IO FilePath
instance GHC.Classes.Eq Data.TLSSetting.TrustedCAStore
instance GHC.Show.Show Data.TLSSetting.TrustedCAStore


-- | This module provides convenience functions for interfacing
--   <tt>io-streams</tt> with <tt>tls</tt>. the default receive buffer size
--   is decided by <tt>tls</tt>. sending is unbuffered, anything write into
--   <a>OutputStream</a> will be immediately send to underlying socket.
--   
--   The same exceptions rule which applied to TCP apply here, with
--   addtional <a>TLSException</a> to be watched out.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import qualified <a>System.IO.Streams.TLS</a> as TLS
--   </pre>
module System.IO.Streams.TLS

-- | Convenience function for initiating an TLS connection to the given
--   <tt>(<a>HostName</a>, <a>PortNumber</a>)</tt> combination.
--   
--   Note that sending an end-of-file to the returned <a>OutputStream</a>
--   will not close the underlying TLS connection; to do that, call
--   <a>close</a>
--   
--   this operation will throw <a>TLSException</a> on failure.
connect :: ClientParams -> Maybe String -> HostName -> PortNumber -> IO (InputStream ByteString, OutputStream ByteString, Context)

-- | Convenience function for initiating an TLS connection to the given
--   <tt>(<a>HostName</a>, <a>PortNumber</a>)</tt> combination. The socket
--   and TLS connection are closed and deleted after the user handler runs.
withConnection :: ClientParams -> Maybe HostName -> HostName -> PortNumber -> (InputStream ByteString -> OutputStream ByteString -> Context -> IO a) -> IO a

-- | Accept a new connection from remote client, return a
--   <a>InputStream</a> / <a>OutputStream</a> pair and remote
--   <a>SockAddr</a>, you should call <a>bindAndListen</a> first.
--   
--   this operation will throw <a>TLSException</a> on failure.
accept :: ServerParams -> Socket -> IO (InputStream ByteString, OutputStream ByteString, Context, SockAddr)

-- | Given an existing TLS <a>Context</a> connection, produces an
--   <a>InputStream</a> / <a>OutputStream</a> pair.
tlsToStreams :: Context -> IO (InputStream ByteString, OutputStream ByteString)

-- | Close a TLS <a>Context</a> and its underlying socket.
close :: Context -> IO ()
