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


-- | A simple SMTP client
--   
--   A simple SMTP client
--   
--   DARCS repository: <a>http://blacksapphire.com/SMTPClient/</a>
@package SMTPClient
@version 0.3


-- | A pure SMTP client state machine.
module Network.SMTP.ClientSession

-- | Construct a pure state machine for an SMTP client session. Caller must
--   handle I/O. The message body may use either "\n" or "\r\n" for an
--   end-of-line marker.
smtpClientSession :: String -> [Message] -> SMTPState
data SMTPState
SMTPState :: [String] -> (String -> SMTPState -> SMTPState) -> Bool -> Maybe String -> [Maybe SmtpReply] -> SMTPState

-- | Step 1. Caller must output any lines queued up in this list. They do
--   not have end-of-line characters, so the caller must add "\r\n" on the
--   end (as required by RFC2821 - not just "\n").
smtpOutQueue :: SMTPState -> [String]

-- | Step 2. When sends are completed, the caller should wait for a line
--   from the SMTP server, strip the "\n" end-of-line characters, and pass
--   the line to this function for processing.
smtpReceive :: SMTPState -> String -> SMTPState -> SMTPState

-- | Step 3. Check if this is True, which indicates that the SMTP session
--   has completed successfully and there is no more work to do.
smtpSuccess :: SMTPState -> Bool

-- | Step 4. Check if this is Just err, which indicates that a protocol
--   error has occurred, and that the caller must terminate the session.
smtpFailure :: SMTPState -> Maybe String

-- | A list containing a failure status for each message that has been sent
--   so far, where each element corresponds to one in the list of messages.
--   If the SMTP session fails part-way through, this list is likely to be
--   shorter than the input messages list. <a>Nothing</a> means success,
--   and <a>Just x</a> is a failure status returned by the SMTP server.
smtpStatuses :: SMTPState -> [Maybe SmtpReply]

-- | An SMTP reply is a three-digit return code plus some waste of
--   bandwidth called "comments". This is what the list of strings is for;
--   one string per line in the reply. <a>show</a> will append an
--   "<tt>\r\n</tt>" end-of-line marker to each entry in that list, so that
--   the resulting string is ready to be sent back to the peer.
--   
--   Here is an example:
--   
--   <tt> *Rfc2821&gt; print $ Reply (Code Success MailSystem 0) ["worked",
--   "like", "a charm" ] 250-worked 250-like 250 a charm </tt>
--   
--   If the message is <tt>[]</tt>, you'll get a really helpful default
--   text.
data SmtpReply :: *
Reply :: SmtpCode -> [String] -> SmtpReply
data SmtpCode :: *
Code :: SuccessCode -> Category -> Int -> SmtpCode
data SuccessCode :: *
Unused0 :: SuccessCode
PreliminarySuccess :: SuccessCode
Success :: SuccessCode
IntermediateSuccess :: SuccessCode
TransientFailure :: SuccessCode
PermanentFailure :: SuccessCode
data Category :: *
Syntax :: Category
Information :: Category
Connection :: Category
Unspecified3 :: Category
Unspecified4 :: Category
MailSystem :: Category

-- | This data type repesents a parsed Internet Message as defined in this
--   RFC. It consists of an arbitrary number of header lines, represented
--   in the <a>Field</a> data type, and a message body, which may be empty.
data Message :: *
Message :: [Field] -> String -> Message

-- | This data type represents any of the header fields defined in this
--   RFC. Each of the various instances contains with the return value of
--   the corresponding parser.
data Field :: *
OptionalField :: String -> String -> Field
From :: [NameAddr] -> Field
Sender :: NameAddr -> Field
ReturnPath :: String -> Field
ReplyTo :: [NameAddr] -> Field
To :: [NameAddr] -> Field
Cc :: [NameAddr] -> Field
Bcc :: [NameAddr] -> Field
MessageID :: String -> Field
InReplyTo :: [String] -> Field
References :: [String] -> Field
Subject :: String -> Field
Comments :: String -> Field
Keywords :: [[String]] -> Field
Date :: CalendarTime -> Field
ResentDate :: CalendarTime -> Field
ResentFrom :: [NameAddr] -> Field
ResentSender :: NameAddr -> Field
ResentTo :: [NameAddr] -> Field
ResentCc :: [NameAddr] -> Field
ResentBcc :: [NameAddr] -> Field
ResentMessageID :: String -> Field
ResentReplyTo :: [NameAddr] -> Field
Received :: ([(String, String)], CalendarTime) -> Field
ObsReceived :: [(String, String)] -> Field

-- | A NameAddr is composed of an optional realname a mandatory e-mail
--   <a>address</a>.
data NameAddr :: *
NameAddr :: Maybe String -> String -> NameAddr
nameAddr_name :: NameAddr -> Maybe String
nameAddr_addr :: NameAddr -> String


-- | An SMTP client in the IO Monad.
module Network.SMTP.Client

-- | Send a list of email messages to an SMTP server. Throws SMTPException
--   on failure at the communication protocol level.
--   
--   The optional IORef is used to store a list of statuses for messages
--   sent so far, where Nothing means success. The list elements correspond
--   to the elements of the input message list. If the caller catches an
--   exception, this list is likely to be shorter than the input message
--   list, and so it gives an indication of how many messages were
--   dispatched.
--   
--   The message body may use either "\n" or "\r\n" for an end-of-line
--   marker and in either case it will be sent correctly to the server.
sendSMTP :: Maybe (IORef [Maybe SmtpReply]) -> String -> SockAddr -> [Message] -> IO ()

-- | Like sendSMTP but takes an additional function for logging all input
--   and output for diagnostic purposes.
sendSMTP' :: (String -> IO ()) -> Maybe (IORef [Maybe SmtpReply]) -> String -> SockAddr -> [Message] -> IO ()

-- | An exception indicating a communications failure at the level of the
--   SMTP protocol.
data SMTPException
SMTPException :: String -> SMTPException

-- | An SMTP reply is a three-digit return code plus some waste of
--   bandwidth called "comments". This is what the list of strings is for;
--   one string per line in the reply. <a>show</a> will append an
--   "<tt>\r\n</tt>" end-of-line marker to each entry in that list, so that
--   the resulting string is ready to be sent back to the peer.
--   
--   Here is an example:
--   
--   <tt> *Rfc2821&gt; print $ Reply (Code Success MailSystem 0) ["worked",
--   "like", "a charm" ] 250-worked 250-like 250 a charm </tt>
--   
--   If the message is <tt>[]</tt>, you'll get a really helpful default
--   text.
data SmtpReply :: *
Reply :: SmtpCode -> [String] -> SmtpReply
data SmtpCode :: *
Code :: SuccessCode -> Category -> Int -> SmtpCode
data SuccessCode :: *
Unused0 :: SuccessCode
PreliminarySuccess :: SuccessCode
Success :: SuccessCode
IntermediateSuccess :: SuccessCode
TransientFailure :: SuccessCode
PermanentFailure :: SuccessCode
data Category :: *
Syntax :: Category
Information :: Category
Connection :: Category
Unspecified3 :: Category
Unspecified4 :: Category
MailSystem :: Category

-- | This data type repesents a parsed Internet Message as defined in this
--   RFC. It consists of an arbitrary number of header lines, represented
--   in the <a>Field</a> data type, and a message body, which may be empty.
data Message :: *
Message :: [Field] -> String -> Message

-- | This data type represents any of the header fields defined in this
--   RFC. Each of the various instances contains with the return value of
--   the corresponding parser.
data Field :: *
OptionalField :: String -> String -> Field
From :: [NameAddr] -> Field
Sender :: NameAddr -> Field
ReturnPath :: String -> Field
ReplyTo :: [NameAddr] -> Field
To :: [NameAddr] -> Field
Cc :: [NameAddr] -> Field
Bcc :: [NameAddr] -> Field
MessageID :: String -> Field
InReplyTo :: [String] -> Field
References :: [String] -> Field
Subject :: String -> Field
Comments :: String -> Field
Keywords :: [[String]] -> Field
Date :: CalendarTime -> Field
ResentDate :: CalendarTime -> Field
ResentFrom :: [NameAddr] -> Field
ResentSender :: NameAddr -> Field
ResentTo :: [NameAddr] -> Field
ResentCc :: [NameAddr] -> Field
ResentBcc :: [NameAddr] -> Field
ResentMessageID :: String -> Field
ResentReplyTo :: [NameAddr] -> Field
Received :: ([(String, String)], CalendarTime) -> Field
ObsReceived :: [(String, String)] -> Field

-- | A NameAddr is composed of an optional realname a mandatory e-mail
--   <a>address</a>.
data NameAddr :: *
NameAddr :: Maybe String -> String -> NameAddr
nameAddr_name :: NameAddr -> Maybe String
nameAddr_addr :: NameAddr -> String
instance Typeable SMTPException
instance Eq SMTPException
instance Show SMTPException
instance Exception SMTPException