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


-- | Simple and easy network connections API
--   
--   Simple network library for all your connection need.
--   
--   Features: Really simple to use, SSL/TLS, SOCKS.
--   
--   This library provides a very simple api to create sockets to a
--   destination with the choice of SSL/TLS, and SOCKS.
@package connection
@version 0.2.6


-- | Simple connection abstraction
module Network.Connection

-- | This opaque type represent a connection to a destination.
data Connection

-- | return a simple tuple of the port and hostname that we're connected
--   to.
connectionID :: Connection -> ConnectionID

-- | Connection Parameters to establish a Connection.
--   
--   The strict minimum is an hostname and the port.
--   
--   If you need to establish a TLS connection, you should make sure
--   connectionUseSecure is correctly set.
--   
--   If you need to connect through a SOCKS, you should make sure
--   connectionUseSocks is correctly set.
data ConnectionParams
ConnectionParams :: HostName -> PortNumber -> Maybe TLSSettings -> Maybe ProxySettings -> ConnectionParams

-- | host name to connect to.
[connectionHostname] :: ConnectionParams -> HostName

-- | port number to connect to.
[connectionPort] :: ConnectionParams -> PortNumber

-- | optional TLS parameters.
[connectionUseSecure] :: ConnectionParams -> Maybe TLSSettings

-- | optional Proxy/Socks configuration.
[connectionUseSocks] :: ConnectionParams -> Maybe ProxySettings

-- | TLS Settings that can be either expressed as simple settings, or as
--   full blown TLS.Params settings.
--   
--   Unless you need access to parameters that are not accessible through
--   the simple settings, you should use TLSSettingsSimple.
data TLSSettings

-- | Simple TLS settings. recommended to use.
TLSSettingsSimple :: Bool -> Bool -> Bool -> TLSSettings

-- | Disable certificate verification completely, this make TLS/SSL
--   vulnerable to a MITM attack. not recommended to use, but for testing.
[settingDisableCertificateValidation] :: TLSSettings -> Bool

-- | Disable session management. TLS/SSL connections will always
--   re-established their context. Not Implemented Yet.
[settingDisableSession] :: TLSSettings -> Bool

-- | Use server name extension. Not Implemented Yet.
[settingUseServerName] :: TLSSettings -> Bool

-- | full blown TLS Settings directly using TLS.Params. for power users.
TLSSettings :: ClientParams -> TLSSettings

-- | Proxy settings for the connection.
--   
--   OtherProxy handles specific application-level proxies like HTTP
--   proxies.
--   
--   The simple SOCKS settings is just the hostname and portnumber of the
--   SOCKS proxy server.
--   
--   That's for now the only settings in the SOCKS package, socks password,
--   or any sort of other authentications is not yet implemented.
data ProxySettings
SockSettingsSimple :: HostName -> PortNumber -> ProxySettings
SockSettingsEnvironment :: (Maybe String) -> ProxySettings
OtherProxy :: HostName -> PortNumber -> ProxySettings
type SockSettings = ProxySettings

-- | This is the exception raised if we reached the user specified limit
--   for the line in ConnectionGetLine.
data LineTooLong
LineTooLong :: LineTooLong

-- | Exception raised when there's no resolution for a specific host
data HostNotResolved
HostNotResolved :: String -> HostNotResolved

-- | Exception raised when the connect failed
data HostCannotConnect
HostCannotConnect :: String -> [IOException] -> HostCannotConnect

-- | Initialize the library with shared parameters between connection.
initConnectionContext :: IO ConnectionContext

-- | Shared values (certificate store, sessions, ..) between connections
--   
--   At the moment, this is only strictly needed to shared sessions and
--   certificates when using a TLS enabled connection.
data ConnectionContext

-- | Use an already established handle to create a connection object.
--   
--   if the TLS Settings is set, it will do the handshake with the server.
--   The SOCKS settings have no impact here, as the handle is already
--   established
connectFromHandle :: ConnectionContext -> Handle -> ConnectionParams -> IO Connection

-- | Use an already established handle to create a connection object.
--   
--   if the TLS Settings is set, it will do the handshake with the server.
--   The SOCKS settings have no impact here, as the handle is already
--   established
connectFromSocket :: ConnectionContext -> Socket -> ConnectionParams -> IO Connection

-- | connect to a destination using the parameter
connectTo :: ConnectionContext -> ConnectionParams -> IO Connection

-- | Close a connection.
connectionClose :: Connection -> IO ()

-- | Get some bytes from a connection.
--   
--   The size argument is just the maximum that could be returned to the
--   user. The call will return as soon as there's data, even if there's
--   less than requested. Hence, it behaves like <a>hGetSome</a>.
--   
--   On end of input, <a>connectionGet</a> returns 0, but subsequent calls
--   will throw an <a>isEOFError</a> exception.
connectionGet :: Connection -> Int -> IO ByteString

-- | Get exact count of bytes from a connection.
--   
--   The size argument is the exact amount that must be returned to the
--   user. The call will wait until all data is available. Hence, it
--   behaves like <a>hGet</a>.
--   
--   On end of input, <a>connectionGetExact</a> will throw an
--   <a>isEOFError</a> exception.
connectionGetExact :: Connection -> Int -> IO ByteString

-- | Get the next block of data from the connection.
connectionGetChunk :: Connection -> IO ByteString

-- | Like <a>connectionGetChunk</a>, but return the unused portion to the
--   buffer, where it will be the next chunk read.
connectionGetChunk' :: Connection -> (ByteString -> (a, ByteString)) -> IO a

-- | Get the next line, using ASCII LF as the line terminator.
--   
--   This throws an <tt>isEOFError</tt> exception on end of input, and
--   LineTooLong when the number of bytes gathered is over the limit
--   without a line terminator.
--   
--   The actual line returned can be bigger than the limit specified,
--   provided that the last chunk returned by the underlaying backend
--   contains a LF. In another world only when we need more input and limit
--   is reached that the LineTooLong exception will be raised.
--   
--   An end of file will be considered as a line terminator too, if line is
--   not empty.
connectionGetLine :: Int -> Connection -> IO ByteString

-- | Put a block of data in the connection.
connectionPut :: Connection -> ByteString -> IO ()

-- | Activate secure layer using the parameters specified.
--   
--   This is typically used to negociate a TLS channel on an already
--   establish channel, e.g. supporting a STARTTLS command. it also flush
--   the received buffer to prevent application confusing received data
--   before and after the setSecure call.
--   
--   If the connection is already using TLS, nothing else happens.
connectionSetSecure :: ConnectionContext -> Connection -> TLSSettings -> IO ()

-- | Returns if the connection is establish securely or not.
connectionIsSecure :: Connection -> IO Bool
instance GHC.Show.Show Network.Connection.HostCannotConnect
instance GHC.Show.Show Network.Connection.HostNotResolved
instance GHC.Show.Show Network.Connection.LineTooLong
instance GHC.Exception.Exception Network.Connection.LineTooLong
instance GHC.Exception.Exception Network.Connection.HostNotResolved
instance GHC.Exception.Exception Network.Connection.HostCannotConnect