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


-- | This module implements the authentication extension to SMTP as defined
--   in RFC 2554.
module Network.Smtp.Ext.Auth


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

-- | Authentication extension.
AuthExt :: (Set AuthMethod) -> Extension

-- | Authentication methods for the SMTP authentication extension.
data AuthMethod

-- | We don't know any authentication methods yet.
AuthMethod :: AuthMethod

-- | 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 AuthMethod
instance Ord AuthMethod
instance Read AuthMethod
instance Show AuthMethod
instance Eq Extension
instance Ord Extension
instance Read Extension
instance Show Extension
instance Eq SmtpResponse
instance Show SmtpResponse
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

-- | Get the next nonempty line from the stream using <a>netLineEmpty</a>.
netLine :: Monad m => Int -> Iteratee ByteString m (Maybe ByteString)

-- | Convert a raw byte stream to a stream of lines based on
--   <a>netLine</a>.
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