Portability | portable |
---|---|
Stability | experimental |
Maintainer | Vincent Hanquez <vincent@snarc.org> |
Safe Haskell | None |
Simple connection abstraction
- data Connection
- connectionID :: Connection -> (HostName, PortNumber)
- data ConnectionParams = ConnectionParams {}
- data TLSSettings
- data SockSettings = SockSettingsSimple HostName PortNumber
- initConnectionContext :: IO ConnectionContext
- data ConnectionContext
- connectFromHandle :: ConnectionContext -> Handle -> ConnectionParams -> IO Connection
- connectTo :: ConnectionContext -> ConnectionParams -> IO Connection
- connectionClose :: Connection -> IO ()
- connectionGet :: Connection -> Int -> IO ByteString
- connectionGetChunk :: Connection -> IO ByteString
- connectionGetChunk' :: Connection -> (ByteString -> (a, ByteString)) -> IO a
- connectionPut :: Connection -> ByteString -> IO ()
- connectionSetSecure :: ConnectionContext -> Connection -> TLSSettings -> IO ()
- connectionIsSecure :: Connection -> IO Bool
Type for a connection
data Connection Source
This opaque type represent a connection to a destination.
connectionID :: Connection -> (HostName, PortNumber)Source
return a simple tuple of the port and hostname that we're connected to.
data ConnectionParams Source
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.
ConnectionParams | |
|
data TLSSettings Source
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.
TLSSettingsSimple | Simple TLS settings. recommended to use. |
| |
TLSSettings Params | full blown TLS Settings directly using TLS.Params. for power users. |
data SockSettings Source
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.
Library initialization
initConnectionContext :: IO ConnectionContextSource
Initialize the library with shared parameters between connection.
data ConnectionContext Source
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.
Connection operation
connectFromHandle :: ConnectionContext -> Handle -> ConnectionParams -> IO ConnectionSource
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
:: ConnectionContext | The global context of this connection. |
-> ConnectionParams | The parameters for this connection (where to connect, and such). |
-> IO Connection | The new established connection on success. |
connect to a destination using the parameter
connectionClose :: Connection -> IO ()Source
Close a connection.
Sending and receiving data
connectionGet :: Connection -> Int -> IO ByteStringSource
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.
connectionGetChunk :: Connection -> IO ByteStringSource
Get the next block of data from the connection.
connectionGetChunk' :: Connection -> (ByteString -> (a, ByteString)) -> IO aSource
Like connectionGetChunk
, but return the unused portion to the buffer,
where it will be the next chunk read.
connectionPut :: Connection -> ByteString -> IO ()Source
Put a block of data in the connection.
TLS related operation
connectionSetSecure :: ConnectionContext -> Connection -> TLSSettings -> IO ()Source
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.
connectionIsSecure :: Connection -> IO BoolSource
Returns if the connection is establish securely or not.