added documentation for pop3.scm

This commit is contained in:
interp 2002-03-29 16:31:51 +00:00
parent 57e2820f37
commit fd095636c5
1 changed files with 106 additions and 1 deletions

View File

@ -5,4 +5,109 @@
\item[Name of the package:] pop3
\end{description}
%
Not implemented yet.
\subsection{Overview}
The POP3 protocol allows access to email on a maildrop server. It is
often used in configurations where users connect from a client machine
which doesn't have a permanent network connection or isn't always
turned on, situations which make local SMTP delivery impossible. It is
the most common form of email access provided by Internet Service
Providers.
Two types of authentication are commonly used. The first, most basic
type involves sending a user's password in clear over the network, and
should be avoided. Unfortunately many POP3 clients only implement this
basic authentication. The digest authentication system involves the
server sending the client a ``challenge'' token; the client encodes
this token with the pass phrase and sends the coded information to the
server. This method avoids sending sensitive information over the
network.
Once connected, a client may request information about the number and
size of the messages waiting on the server, download selected messages
(either their headers or the entire content), and delete selected
messages.
\subsection{Entry points}
\begin{defundesc}{pop3:connect}{\ovar{host \ovar{logfile}}}{connection}
Connect to the maildrop server named \semvar{host}. Optionally log
the conversation with the server to \semvar{logfile}, which will be
appended to if it exists, and created otherwise. The environment
variable \ex{MAILHOST}, if set, will override the value of
\semvar{host}.
\end{defundesc}
In the further descriptions of the procedures, \semvar{connection}
always refers to the result of \ex{pop3:\ob{}connect}.
\begin{defundesc}{pop3:login} {connection \ovar{login \ovar{password}}}{status}
Log in to the mailhost. If a \semvar{login} and \semvar{password}
are not provided, they are first searched for in the user's ~/.netrc
file. USER/PASS authentication will be tried first, and if
this fails, APOP authentication (secure) will be tried.
\end{defundesc}
\begin{defundesc}{pop3:login/APOP} {connection login password}{status}
Log in to the mailhost using APOP authentication. \footnote{The encryption
(MD5) is currently done by an extern program that your system must
provide. The expected name of the program is \ex{md5sum}. If your system
uses another program for computing a MD5 message digest, change the
program's name in \ex{md5-digest}.}
\end{defundesc}
\begin{defundesc}{pop3:stat}{connection}{number bytes}
Return the number of messages and the number of bytes waiting in the
maildrop.
\end{defundesc}
\begin{defundesc}{pop3:get}{connection msgid}{status}
Download message number \semvar{msgid} from the mailhost.
\semvar{msgid} must be positive and less than the number of messages
returned by the \ex{pop3:\ob{}stat} call. The message contents are sent to
\ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}.
\end{defundesc}
\begin{defundesc}{pop3:headers}{connection msgid}{status}
Download the headers of message number \semvar{msgid}. The data is sent to
\ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}.
\end{defundesc}
\begin{defundesc}{pop3:last}{connection}{msgid}
Return the highest accessed message-id number for the current
session. This isn't in the RFC, but seems to be supported by several
servers.
\end{defundesc}
\begin{defundesc}{pop3:delete}{connection msgid}{status}
Mark message number \semvar{msgid} for deletion. The message will
not be deleted until the client logs out.
\end{defundesc}
\begin{defundesc}{pop3:reset}{connection}{status}
Any messages which have been marked for deletion are unmarked.
\end{defundesc}
\begin{defundesc}{pop3:quit}{connection}{status}
Close the connection with the mailhost.
\end{defundesc}
\subsection{Related work}
\begin{itemize}
\item Emacs is distributed with a C program called \ex{movemail} which
can be compiled with support for the POP protocol. There is also an
Emacs Lisp library called \ex{pop3.el} by Richard Pieri which
includes APOP support.
\item Shriram Krishnamurth has written a POP3 library for MzScheme (as
well as support for the NNTP protocol, for SMTP, \ldots).
\item Siod (a small-footprint Scheme implementation by George Carette)
includes support for the POP3 protocol.
\item rfc1939 describes the POP3 protocol.
\end{itemize}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End: