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


-- | 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 = MailT r IO

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

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

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

-- | Write timeout in milliseconds.
mailWriteTimeout :: MailConfig -> Int

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

-- | DATA.
SmtpDataCmd :: SmtpCommand

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

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

-- | QUIT.
SmtpQuitCmd :: SmtpCommand

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

-- | RSET.
SmtpResetCmd :: SmtpCommand

-- | VRFY with the given user name.
SmtpVerifyCmd :: ByteString -> SmtpCommand

-- | Waiting for welcome message.
SmtpWelcomeCmd :: 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 a <a>TimeoutError</a> exception is thrown via
--   <a>throwError</a>.
--   
--   Note that this timeout is not a timeout for the whole enumeration, but
--   for each individual read operation. In other words, this timeout
--   protects against dead/unresponsive peers, but not against (perhaps
--   intentionally) slowly sending peers.
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

-- | 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 protocol line length
--   limit (first argument), response lines limit (second argument) and
--   output handle. The input is supplied by an <a>Enumerator</a> such as
--   <a>enumHandleTimeout</a>.
--   
--   The inner iteratee uses <a>SmtpResponse</a> as its input type and
--   hence expects the <a>netLines</a> and <a>smtpResponses</a> enumeratees
--   to be applied. This is done by <a>runMailT</a> for you, so the
--   resulting iteratee takes a raw <a>ByteString</a> stream as input.
runMailT :: (Applicative m, Monad m) => Int -> Int -> Handle -> MailT a m a -> Iteratee ByteString m a

-- | Set the write timeout for the current mail session in milliseconds.
mailSetWriteTimeout :: Int -> MailT r m ()

-- | 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. Please note: This iteratee violates the
--   standard by recognizing a 250 result code as success.
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 ()

-- | Send the <i>VRFY</i> command to find out, whether the mail exchangers
--   knows the given user. Nowadays most mail exchangers disable this
--   command for security reasons.
--   
--   Please note that many SMTP servers will give you false positives or
--   false negatives to prevent spamming attempts. It is not recommended to
--   use this command.
verify :: MonadIO m => ByteString -> MailT r m Bool

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

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

-- | Read/write timeout in milliseconds.
mailTimeoutIO :: 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 be
--   unbuffered. See <a>hSetBuffering</a> and <a>hSetBinaryMode</a>.
sendMail :: (Applicative m, MonadIO m) => SendMail -> MailT a m a -> m (Either SomeException a)

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


-- | 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 <tt>r</tt> type parameter is related to contstuff's
--   <tt>StateT</tt> monad transformer, which is used internally. If you
--   don't know what to do, just leave it fully polymorphic like in the
--   example above. You only need to care about <tt>r</tt>, if you want to
--   make use of the CPS features of <tt>StateT</tt>.
--   
--   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>. 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). This is not
--   possible with the higher level functions.
module Network.Smtp