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


-- | 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 -> (HostName, PortNumber)

-- | 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 SockSettings -> 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 Socks configuration.
connectionUseSocks :: ConnectionParams -> Maybe SockSettings

-- | 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 :: Params -> TLSSettings

-- | Socks settings for the connection.
--   
--   The simple settings is just the hostname and portnumber of the proxy
--   server.
--   
--   That's for now the only settings in the SOCKS package, socks password,
--   or authentication is not yet implemented.
data SockSettings
SockSettingsSimple :: HostName -> PortNumber -> SockSettings

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

-- | 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, however the call will returns as soon as there's data, even if
--   there's less data than expected.
connectionGet :: 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

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