scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

added docu on SMTP

This commit is contained in:
interp 2002-04-02 20:16:47 +00:00
parent 3a14b095e2
commit 437ff2dd56
1 changed files with 367 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

368
doc/latex/smtp.tex
View File

@ -5,4 +5,370 @@
\item[Name of the package:] smtp
\end{description}
%
Not implemented yet.
\subsection{Philosophy}
SMTP protocol procedures tend to return two values:
\begin{description}
\item{\semvar{code}} The integer SMTP reply code returned by server for the transaction.
\item{\semvar{text}} A list of strings -- the text messages tagged by
the code.
\end{description}
The text strings have the initial code numerals and the terminating
\ex{CR}/\ex{LF}'s stripped. Codes in the range $[1,399]$ are sucess
codes; codes in the range $[400,599]$ are error codes; codes $>= 600$
are not part of the official SMTP spec. This module uses codes $>=
600$ to indicate extra-protocol errors. There are two of these:
\begin{description}
\item{600 Server reply could not be parsed.}
The server sent back some sort of incomprehensible garbage reply.
\item{621 Premature EOF while reading server reply.}
The server shut down in the middle of a reply.
\end{description}
A list of the official protocol return codes can be seen in table
\ref{smtp-reply-codes}.
\subsection{Procedures}
\begin{defundesc}{sendmail}{to-list body \ovar{host}}{code text-list}
Mail message \semvar{body} to recipients in list \semvar{to-list}.
Message handed off to server running on \semvar{host}; default is
the local host. Returns two values: \semvar{code} and
\semvar{text-list}, i.e. the code returned by the server and the
text-message, seperated by lines. However, if some recipients were
rejected, sendmail sends to the rest of the recipients, and the
partial-success return is [700 \semvar{loser-alist}] where
\semvar{loser-alist} is a list whose elements are of the form
\ex{(\semvar{loser-recipient} \semvar{code} . \semvar{text})} --
that is, for each recipient refused by the server, you get the error
data sent back for that guy. The success check is \ex{(< code 400)}.
\end{defundesc}
\begin{defundesc}{\%sendmail}{from local-host to dest-host
message}{code text} Mail \semvar{message} to recipient \semvar{to}
using \semvar{dest-host}, telling \semvar{from} as your mail-address
and \semvar{local-host} as your system-name.
\end{defundesc}
\defun{expn}{name host}{code text}
\defunx{vrfy}{name host}{code text}
\defunx{mail-help}{host \ovar{details}}{code text-list}
\begin{desc}
These three are simple queries of the server as stated in the
RFC~821: \ex{expn} asks the server to confirm that the argument
identifies a mailing list, and if so, to return the membership of
that list. The full name of the users (if known) and the fully
specified mailboxes are returned in a multiline reply. \ex{vrfy}
asks the receiver to confirm that the argument identifies a user.
If it is a user name, the full name of the user (if known) and the
fully specified mailbox are returned. \ex{mail-help} causes the
server to send helpful information. The command may take an argument
(\semvar{details}) (e.g., any command name) and return more specific
information as a response.
\end{desc}
\dfn{smtp-transactions}{socket ?transaction1 ...}{code
text-list}{syntax}
\dfnx{smtp-transactions/no-close}{socket ?transaction1 ...}{code
text-list}{syntax}
\begin{desc}
These macros make it easy to do simple sequences of SMTP commands.
Evaluate a series of expressions \semvar{?transaction1},
\semvar{?transaction2}, \ldots
\begin{itemize}
\item Each expression should perform an SMTP transaction, and return
two values: \semvar{code} (the integer reply code) and \semvar{text}
(list of strings that came with the reply).
\item If the transaction's reply code is 221 or 421 (meaning the
socket has been closed), then the transaction sequence is is
aborted, and the \ex{smtp\=trans\ob{}actions} form returns the
\semvar{code} and \semvar{text} values for the current transaction.
\item If the reply code is an error code (in the four- or five-hundred
range), the transaction sequence is aborted, and the fatal
transaction's \semvar{code} and \semvar{text} values are returned.
\ex{smtp\=trans\ob{}actions} will additionally close the socket for
you; \ex{smtp-trans\ob{}actions/\ob{}no\=close} will not.
\item If the transaction is the last in the transaction sequence, its
\semvar{code} and \semvar{text} values are returned.
\item Otherwise, we throw away the current \semvar{code} and
\semvar{text} values, and proceed to the next transaction.
\end{itemize}
Since \ex{smtp-trans\ob{}actions} closes the socket whenever it
aborts a sequence, an \ex{smtp-trans\ob{}actions} form terminated
with an \ex{(smtp/\ob{}quit socket)} transaction will always close
the socket.
If the socket should be kept open in the case of an abort, use
\ex{smtp-trans\ob{}actions/\ob{}no\=close}.
We abort sequences if a transaction results in a 400-class error code.
So, a sequence mailing a message to five people, with 5 RCPT's, would
abort if the mailing address for one of these people was wrong, rather
than proceeding to mail the other four. This may not be what you want;
if so, you'll have to roll your own.
\end{desc}
\defun{smtp/open}{host \ovar{maybe-port}}{socket}
\defunx{smtp/helo}{local-host-name}{code text-list}
\defunx{smtp/mail}{sender-address}{code text-list}
\defunx{smtp/rcpt}{destination-address}{code text-list}
\defunx{smtp/data}{socket message}{code text-list}
\defunx{smtp/send}{sender-address}{code text-list}
\defunx{smtp/soml}{sender-address}{code text-list}
\defunx{smtp/saml}{sender-address}{code text-list}
\defunx{smtp/rset}{}{code text-list}
\defunx{smtp/vrfy}{user}{code text-list}
\defunx{smtp/expn}{user}{code text-list}
\defunx{smtp/help}{details}{code text-list}
\defunx{smtp/noop}{}{code text-list}
\defunx{smtp/quit}{socket}{code text-list}
\defunx{smtp/turn}{}{code text-list}
\begin{desc}
These functions implement the basics of the protocol, i.e. they send
the corresponding command along with the argument(s), if any. A
short look to the code of \ex{\%sendmail} will give you the basics
on how to use the commands. You will obtain further informations in
the RFC~821. \semvar{host}, \semvar{local-host},
\semvar{sender-address}, \semvar{destination-address}, \semvar{user}
and \semvar{details} are strings, \semvar{message} may be a string
or an input-port. \semvar{socket} is a socket, mostly one returned
by \ex{smtp/\ob{}open}.
\end{desc}
\begin{defundesc}{handle-smtp-reply}{socket}{code text-list}
Read and handle the reply. Return an integer (the reply
\semvar{code}), and a list of the text lines (\semvar{text-list})
that came tagged by the reply code. The text lines have the
reply-code prefix (first 4 chars) and the terminating cr/lf's
stripped.
\end{defundesc}
\begin{defundesc}{read-smtp-reply}{port}{code text-list}
Read a reply from the SMTP server. Returns two values:
\begin{description}
\item{\semvar{code}} Integer. The reply code.
\item{\semvar{text}} String list. A list of the text lines comprising
the reply. Each line of text is stripped of the initial
reply-code numerals (e.g., the first four chars of the reply),
and the trailing cr/lf. We are in fact generous about what we
take to be a line -- the protocol requires cr/lf terminators, but
we'll accept just lf. This appears to true to the spirit of the
"be strict in what you send, and generous in what you accept"
Internet protocol philosphy.
\end{description}
\end{defundesc}
\begin{defundesc}{parse-smtp-reply}{line}{code rest more?}
Parse a line of SMTP reply. Return three values:
\begin{description}
\item{\semvar{code}} integer -- the reply code that prefixes the
string.
\item{\semvar{rest}} string -- the rest of the line.
\item{\semvar{more?}} boolean -- is there more reply to read (i.e.,
was the numeric reply code terminated by a ``\ex{-}'' character?)
\end{description}
\end{defundesc}
\begin{defundesc}{smtp-stuff}{text pchar}{stuffed-string last-char}
The message body of a piece of email is terminated by the sequence
\ex{<CRLF> <period> <CRLF>}, i.e. end-of-line, period,
end-of-line. If the message body contains this magic sequence, it
has to be escaped. We do this by mapping the sequence \ex{<LF>
<period>} to \ex{<lf> <period> <period>}; the SMTP receiver undoes
this mapping.
\semvar{text} is a string to stuff, \semvar{pchar} was the character
read just before \semvar{text} (which matters if it is a line-feed).
If \semvar{text} is the first chunk of the entire msg, then
\semvar{pchar} can be \sharpf. Return two values: the
\semvar{stuffed-string}, and the last char in \semvar{text} (or
\semvar{pchar} if \semvar{text} is empty). The last-char value
returned can be used as the \semvar{pchar} arg for the following
call to \ex{smtp\=stuff}.
\end{defundesc}
\subsection{Additional information about SMTP}
\subsubsection*{Reply codes}
This material is taken from the RFC. The first digits encode categories
of responses:
\begin{description}
\item{\bfseries 1yz Positive Preliminary reply\,} The command has been
accepted, but the requested action is being held in abeyance,
pending confirmation of the information in this reply. The
sender-SMTP should send another command specifying whether to
continue or abort the action.
\begin{leftinset}
Note: SMTP does not have any commands that allow this type of reply,
and so does not have the continue or abort commands.
\end{leftinset}
\item{\bfseries 2yz Positive Completion reply\,} The requested action has
been successfully completed. A new request may be initiated.
\item{\bfseries 3yz Positive Intermediate reply\,} The command has been
accepted, but the requested action is being held in abeyance,
pending receipt of further information. The sender-SMTP should send
another command specifying this information. This reply is used in
command sequence groups.
\item{\bfseries 4yz Transient Negative Completion reply\,} The command was
not accepted and the requested action did not occur. However, the
error condition is temporary and the action may be requested again.
The sender should return to the beginning of the command sequence
(if any). It is difficult to assign a meaning to ``transient'' when
two different sites (receiver- and sender- SMTPs) must agree on the
interpretation. Each reply in this category might have a different
time value, but the sender-SMTP is encouraged to try again. A rule
of thumb to determine if a reply fits into the 4yz or the 5yz
category (see below) is that replies are 4yz if they can be repeated
without any change in command form or in properties of the sender or
receiver. (E.g., the command is repeated identically and the
receiver does not put up a new implementation.)
\item{\bfseries 5yz Permanent Negative Completion reply\,} The command was
not accepted and the requested action did not occur. The
sender-SMTP is discouraged from repeating the exact request (in the
same sequence). Even some ``permanent'' error conditions can be
corrected, so the human user may want to direct the sender-SMTP to
reinitiate the command sequence by direct action at some point in
the future (e.g., after the spelling has been changed, or the user
has altered the account status).
\end{description}
The second digit encodes responses in specific categories:
\begin{description}
\item{\bfseries x0z Syntax\,} These replies refer to syntax errors,
syntactically correct commands that don't fit any functional
category, and unimplemented or superfluous commands.
\item{\bfseries x1z Information\,} These are replies to requests for
information, such as status or help.
\item{\bfseries x2z Connections\,} These are replies referring to the
transmission channel.
\item{\bfseries x3z\,} Unspecified as yet.
\item{\bfseries x4z\,} Unspecified as yet.
\item{\bfseries x5z Mail system\,} These replies indicate the status of the
receiver mail system vis-a-vis the requested transfer or other mail
system action.
\end{description}
\begin{table}
\label{smtp-reply-codes}
\begin{tabular}{|lp{10cm}|}
\hline
500 & Syntax error, command unrecognized \newline
[This may include errors such as command line too long] \\
501 & Syntax error in parameters or arguments \\
502 & Command not implemented\\
503 & Bad sequence of commands\\
504 & Command parameter not implemented\\
\hline
211 & System status, or system help reply\\
214 & Help message \newline
[Information on how to use the receiver or the meaning of a
particular non-standard command; this reply is useful only
to the human user]\\
\hline
220 & \semvar{domain} Service ready \\
221 & \semvar{domain} Service closing transmission channel\\
421 & \semvar{domain} Service not available,
closing transmission channel\newline
[This may be a reply to any command if the service knows it
must shut down]\\
\hline
250 & Requested mail action okay, completed\\
251 & User not local; will forward to \semvar{forward-path}\\
450 & Requested mail action not taken: mailbox unavailable
[E.g., mailbox busy]\\
550 & Requested action not taken: mailbox unavailable
[E.g., mailbox not found, no access]\\
451 & Requested action aborted: error in processing\\
551 & User not local; please try \semvar{forward-path}\\
452 & Requested action not taken: insufficient system storage\\
552 & Requested mail action aborted: exceeded storage allocation\\
553 & Requested action not taken: mailbox name not allowed
[E.g., mailbox syntax incorrect]\\
354 & Start mail input; end with \ex{CRLF}.\ex{CRLF}\\
554 & Transaction failed\\
\hline
\end{tabular}
\caption{Complete list of SMPT reply-codes.}
\end{table}
\begin{table}
\label{smtp-command-reply-codes}
\begin{tabular}{|p{2.3cm}||p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|}
\hline
\bf{What} & \bf{intermediate} & \bf{success} & \bf{failure} & \bf{error}\\
\hline
\hline
conn. establ. & &
220 &
421 &\\
HELO & &
250 & &
500, 501, 504, 421\\
MAIL & &
250 &
552, 451, 452 &
500, 501, 421\\
RCPT & &
250, 251 &
550, 551, 552, 553, 450, 451, 452 &
500, 501, 503, 421\\
DATA &
354 \verb|->| data &
250 &
552, 554, 451, 452 & \\ & otherwise & &
451, 554 &
500, 501, 503, 421\\
RSET & &
250 & &
500, 501, 504, 421\\
SEND & &
250 &
552, 451, 452 &
500, 501, 502, 421\\
SOML & &
250 &
552, 451, 452 &
500, 501, 502, 421\\
SAML & &
250 &
552, 451, 452 &
500, 501, 502, 421\\
VRFY & &
250, 251 &
550, 551, 553 &
500, 501, 502, 504, 421\\
EXPN & &
250 &
550 &
500, 501, 502, 504, 421\\
HELP & &
211, 214 & &
500, 501, 502, 504, 421\\
NOOP & &
250 & &
500, 421\\
QUIT & &
221 & &
500\\
TURN & &
250 &
502 &
500, 503\\
\hline
\end{tabular}
\caption{command--reply sequences.}
\end{table}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End: