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


-- | Advanced ESMTP library
--   
--   This library provides fast, incremental client-side ESMTP sessions for
--   mail exchangers and mail transfer agents.
@package ismtp
@version 2.0.0


-- | Types used by ismtp.
module Network.Smtp.Types

-- | The <a>Mail</a> monad is <a>MailT</a> over <a>IO</a>.
type Mail r a = MailT r IO a

-- | The <a>MailT</a> monad transformer encapsulates an SMTP session.
type MailT r m = Iteratee SmtpResponse (StateT r MailConfig m)

-- | Convenient type alias for raw streams. Needed by
--   <tt>Network.Smtp.Monad.runMailT</tt>.
type StringMailT r m = Iteratee ByteString (StateT r MailConfig m)

-- | SMTP service extension.
data Extension

-- | We don't support any extensions yet.
Extension :: Extension

-- | Mail session configuration.
data MailConfig
MailConfig :: Set Extension -> Handle -> MailConfig

-- | Supported extensions.
mailExtensions :: MailConfig -> Set Extension

-- | Connection handle.
mailHandle :: MailConfig -> Handle

-- | Failed SMTP command (used by <a>SmtpException</a>).
data SmtpCommand

-- | Waiting for welcome message.
SmtpWelcomeCmd :: SmtpCommand

-- | EHLO or HELO with domain.
SmtpHelloCmd :: ByteString -> SmtpCommand

-- | MAIL FROM with address.
SmtpMailFromCmd :: ByteString -> SmtpCommand

-- | RCPT TO with address.
SmtpRcptToCmd :: ByteString -> SmtpCommand

-- | DATA.
SmtpDataCmd :: SmtpCommand

-- | RSET.
SmtpResetCmd :: SmtpCommand

-- | QUIT.
SmtpQuitCmd :: SmtpCommand

-- | SMTP exception.
data SmtpException
SmtpException :: String -> SmtpCommand -> Integer -> String -> SmtpException
smtpErrorMessage :: SmtpException -> String
smtpErrorCommand :: SmtpException -> SmtpCommand
smtpErrorCode :: SmtpException -> Integer
smtpErrorServerMessage :: SmtpException -> String

-- | SMTP response.
data SmtpResponse
SmtpResponse :: Integer -> Vector ByteString -> SmtpResponse

-- | Three digit response code.
smtpCode :: SmtpResponse -> Integer

-- | Messages sent with the code.
smtpMessages :: SmtpResponse -> Vector ByteString
instance Typeable SmtpException
instance Eq SmtpResponse
instance Show SmtpResponse
instance Eq Extension
instance Ord Extension
instance Show SmtpException
instance Exception SmtpException


-- | Helper functions and types.
module Network.Smtp.Tools

-- | Enumerate from a handle with the given buffer size (first argument)
--   and timeout in milliseconds (second argument). If the timeout is
--   exceeded an exception is thrown via <a>throwError</a>.
enumHandleTimeout :: MonadIO m => Int -> Int -> Handle -> Enumerator ByteString m b

-- | Format a <a>Vector</a> of <a>ByteString</a> messages from an
--   <a>SmtpResponse</a> for output.
formatMsgs :: Vector ByteString -> String

-- | Savely read a line with the given maximum length. If a longer line is
--   enumerated, the excess data is dropped in constant space. Returns
--   <a>Nothing</a> on EOF.
netLine :: Monad m => Int -> MaybeT r (Iteratee ByteString m) ByteString

-- | Convert a stream of bytes to a stream of lines with the given maximum
--   length. Longer lines are silently truncated in constant space.
netLines :: Monad m => Int -> Enumeratee ByteString ByteString m b

-- | Composition of all <a>Enumeratee</a>s, which are needed to convert a
--   raw <a>ByteString</a> stream to an <a>SmtpResponse</a> stream. This
--   function takes the maximum line length and the response line limit as
--   its first two parameters.
responseLines :: Monad m => Int -> Int -> Iteratee SmtpResponse m b -> Iteratee ByteString m b

-- | Read the next SMTP response line from the given <a>ByteString</a>
--   lines stream (i.e. a <a>ByteString</a> stream converted by
--   <a>netLines</a>). Returns <a>Nothing</a> on EOF. Returns <tt>Just
--   (Left line)</tt>, if the next line is not a proper SMTP response.
--   Otherwise returns <tt>(code, more, msg)</tt>.
smtpResponseLine :: Monad m => MaybeT r (Iteratee ByteString m) (Either ByteString (Integer, Bool, ByteString))

-- | Read the next SMTP response from a <a>netLines</a>-splitted
--   <a>ByteString</a> stream. Throws an error on protocol errors. Returns
--   at most the given number of response messages.
smtpResponse :: Monad m => Int -> MaybeT r (Iteratee ByteString m) SmtpResponse

-- | Convert a stream of <a>netLines</a>-splitted <a>ByteString</a> lines
--   to a stream of SMTP responses. In case of a protocol error the
--   enumeration is aborted and an error is thrown.
smtpResponses :: Monad m => Int -> Enumeratee ByteString SmtpResponse m b

-- | Convert extension string to <a>Extension</a> value, if the
--   corresponding extension is known.
stringToExtension :: ByteString -> Maybe Extension


-- | This module implements a monad for SMTP sessions.
module Network.Smtp.Monad

-- | Run a mail session computation with the given output handle. The input
--   is supplied by an <a>Enumerator</a> such as <a>enumHandleTimeout</a>.
runMailT :: (Applicative m, Monad m) => Handle -> StringMailT (Either SomeException a) m a -> m (Either SomeException a)

-- | Run a mail session computation using <a>runMailT</a> and throw an
--   exception on error.
runMailT_ :: (Applicative m, MonadIO m) => Handle -> StringMailT (Either SomeException a) m a -> m a

-- | Format a bad response together with the supplied error message and
--   throw an <a>SmtpException</a> in the underlying <a>Iteratee</a>.
mailError :: Monad m => SmtpCommand -> String -> Integer -> Vector ByteString -> MailT r m a

-- | Send a stream of <a>ByteString</a>s to the SMTP server.
mailPut :: MonadIO m => Enumerator ByteString (MailT r m) () -> MailT r m ()

-- | Send a list of <a>ByteString</a>s followed an SMTP line terminator to
--   the SMTP server.
mailPutLn :: MonadIO m => [ByteString] -> MailT r m ()

-- | Retrieve the next SMTP response. Throw an <a>Error</a>, if there is no
--   next response.
nextResponse :: Monad m => MailT r m SmtpResponse


-- | SMTP session computations.
module Network.Smtp.Session

-- | Try <i>EHLO</i> with fallback to <i>HELO</i>.
hello :: MonadIO m => ByteString -> MailT r m ()

-- | Send the <i>DATA</i> command along with the mail content. Please note
--   that the last line must be properly terminated by CRLF.
mailData :: MonadIO m => Enumerator ByteString (MailT r m) () -> MailT r m ()

-- | <a>ByteString</a> interface to <a>mailData</a>.
mailDataStr :: MonadIO m => ByteString -> MailT r m ()

-- | Send <i>MAIL FROM</i> command.
mailFrom :: MonadIO m => ByteString -> MailT r m ()

-- | Send <i>QUIT</i> command.
quit :: MonadIO m => MailT r m ()

-- | Send <i>RCPT TO</i> command.
rcptTo :: MonadIO m => ByteString -> MailT r m ()

-- | Send <i>RSET</i> command.
reset :: MonadIO m => MailT r m ()

-- | Wait for the welcome greeting from the SMTP server.
waitForWelcome :: Monad m => MailT r m ()


-- | Higher level interface to ismtp.
module Network.Smtp.Simple

-- | Session configuration.
data SendMail
SendMail :: Int -> Handle -> Int -> Int -> Handle -> Int -> SendMail

-- | Input buffer size.
mailBufferSize :: SendMail -> Int

-- | Input handle (e.g. receiving socket).
mailInputHandle :: SendMail -> Handle

-- | Maximum line length (flood protection).
mailMaxLine :: SendMail -> Int

-- | Maximum number of messages (flood protection).
mailMaxMessages :: SendMail -> Int

-- | Output handle (e.g. sending socket).
mailOutputHandle :: SendMail -> Handle

-- | Receive timeout in milliseconds.
mailTimeout :: SendMail -> Int

-- | Default values for <a>SendMail</a> with the given input and output
--   handle respectively.
defSendMail :: Handle -> Handle -> SendMail

-- | Execute the given mail session using the supplied configuration.
--   Please note that both handles must be set to binary mode and the input
--   handle should be unbuffered (<a>NoBuffering</a>).
sendMail :: (Applicative m, MonadIO m) => SendMail -> MailT (Either SomeException a) m a -> m (Either SomeException a)

-- | Like <a>sendMail</a>, but throws an exception on error.
sendMail_ :: (Applicative m, MonadIO m) => SendMail -> MailT (Either SomeException a) m a -> m a


-- | High level interfaces for networking.
module Network.Smtp.Connect

-- | Interface to <a>withSmtpConn</a>, which connects to the first mail
--   exchanger (MX) of the given domain on port 25. The <a>Bool</a>
--   parameter specifies whether to fall back to the given domain itself,
--   if no MX records can be found.
withMxConn :: (Applicative m, DnsMonad m, MonadPeelIO m) => Domain -> Bool -> MailT (Either SomeException a) m a -> m a

-- | Connect to the specified SMTP server and run the given computation.
--   Note that there is also <a>withMxConn</a>, which resolves the MX
--   server of the given domain.
withSmtpConn :: (Applicative m, MonadPeelIO m) => HostName -> PortID -> MailT (Either SomeException a) m a -> m a

-- | Perform some useful (but not necessarily needed) initialization like
--   disabling SIGPIPE and initializing sockets, run the given computation
--   and then clean up.
withIsmtp :: IO a -> IO a

-- | Disable the <i>SIGPIPE</i> signal, so our program doesn't die on
--   broken pipes.
ignoreSigPipe :: IO ()

-- | Run the given computation with the <i>SIGPIPE</i> signal disabled, so
--   our program doesn't die on broken pipes.
withIgnoredSigPipe :: IO a -> IO a


-- | This package provides a monad transformer for fast, incremental ESMTP
--   sessions, with which you can, among other things, send emails. Here is
--   an example session:
--   
--   <pre>
--   import Network.Smtp
--   
--   mailSession ::
--       MonadIO m =&gt;
--       ByteString -&gt; ByteString -&gt; ByteString -&gt; ByteString -&gt; MailT r m ()
--   mailSession srcDomain fromAddr toAddr content = do
--       waitForWelcome
--       hello srcDomain
--       mailFrom fromAddr
--       rcptTo toAddr
--       mailDataStr content
--       quit
--   </pre>
--   
--   The simplest interfaces to running SMTP sessions are
--   <a>withSmtpConn</a> and <a>withMxConn</a>. The latter does a DNS
--   lookup for the given domain to discover the MX server and connect to
--   it. The former simply connects to the given hostname and port.
--   
--   If you need more control over the connection handles and other
--   parameters like timeout and flood protection, you may want to use
--   <a>sendMail</a> or <a>sendMail_</a> instead. Those functions are also
--   useful, if you want to run an SMTP session using stdin and stdout for
--   testing and other purposes.
--   
--   Finally you can use the low level interface for running sessions. See
--   the <a>runMailT</a> function along with <a>enumHandleTimeout</a> and
--   <a>responseLines</a>. This way you get the full power of iteratees.
--   For example you can run the session through a custom enumeratee, which
--   enables you to wrap the session in another protocol (e.g. proxy
--   servers or SSL).
module Network.Smtp