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

Reasonably complete and up-to-date docs for POP3.

This commit is contained in:
sperber 2003-01-21 08:49:18 +00:00
parent 0cb68b88c9
commit be87dc978e
1 changed files with 71 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
doc/latex/pop3.tex
View File

@ -1,119 +1,96 @@
\section{Using POP3}\label{cha:pop3} \chapter{Using POP3}\label{cha:pop3}
% %
\begin{description} The \ex{pop3} structure provides a client for the POP3 protocol that
\item[Used files:] pop3.scm pop3-obsolete.scm allows access to email on a maildrop server. It is often used in
\item[Name of the package:] pop3 pop3-obsolete.scm configurations where users connect from a client machine which doesn't
\end{description} have a permanent network connection or isn't always turned on,
% situations which make local SMTP delivery impossible. It is the most
\section{Overview} common form of email access provided by ISPs.
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 Two types of authentication are commonly used. The first, most basic
type involves sending a user's password in clear over the network, and type involves sending a user's password in clear over the network, and
should be avoided. Unfortunately many POP3 clients only implement this should be avoided. (Unfortunately, many POP3 clients only implement this
basic authentication. The digest authentication system involves the basic authentication.) The digest authentication system involves the
server sending the client a ``challenge'' token; the client encodes server sending the client a ``challenge'' token; the client encodes
this token with the pass phrase and sends the coded information to the this token with the pass phrase and sends the coded information to the
server. This method avoids sending sensitive information over the server. This method avoids sending sensitive information over the
network. network. Both methods are implemented by \ex{pop3}.
Once connected, a client may request information about the number and Once connected, a client may request information about the number and
size of the messages waiting on the server, download selected messages size of the messages waiting on the server, download selected messages
(either their headers or the entire content), and delete selected (either their headers or the entire content), and delete selected
messages. messages.
The procedures defined here raise an error detectable via
\ex{pop3-error?} upon protocol errors with the POP3 server.
\section{Entry points} \defun{pop3-connect}{[host-or-\sharpf] [login-or-\sharpf]
[password-or-\sharpf] [log-port]}{connection}
\begin{desc}
This procedure connects to the maildrop server named \var{host},
and logs in using the provided login name and password. Any of
these can be omitted or \sharpf, in which case the procedure uses
defaults: \ex{MAILHOST} for the host, and \ex{~/.netrc}-provided
values for login and password. If \var{log-port} is provided, the
conversation to the server is logged to the specified output port.
\begin{defundesc}{pop3-connect}{[host] [logfile]}{connection} \ex{Pop3-connect} returns a value representing the connection to the
Connect to the maildrop server named \semvar{host}. Optionally log POP3 server, to be used in the procedures below.
the conversation with the server to \semvar{logfile}, which will be \end{desc}
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} \defun{pop3-stat}{connection}{number bytes}
always refers to the result of \ex{pop3-\ob{}connect}. \begin{desc}
This returns the number of messages and the number of bytes waiting in the
\begin{defundesc}{pop3-login} {connection [login] [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. maildrop.
\end{defundesc} \end{desc}
\begin{defundesc}{pop3-get}{connection msgid}{status} Most of the following procedures accept a \var{msgid} argument which
Download message number \semvar{msgid} from the mailhost. specifies a message number, which ranges from 1 for the first message
\semvar{msgid} must be positive and less than the number of messages to the number returned by \ex{pop3-stat}.
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} \defun{pop3-retrieve-message}{connection msgid}{headers message}
Download the headers of message number \semvar{msgid}. The data is sent to \begin{desc}
\ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}. This downloads message number \var{msgid} from the mailhost.
\end{defundesc} It returns the headers as an alist of field names and bodies; the
names are symbols, the bodies are strings. (These are obtained
using the \ex{rfc822} structure, see Section~\ref{cha:rfc822}.)
The message is returned as a list of strings, each string
representing a line of the message.
\end{desc}
\begin{defundesc}{pop3-last}{connection}{msgid} \defun{pop3-retrieve-headers}{connection msgid}{headers}
Return the highest accessed message-id number for the current \begin{desc}
session. This isn't in the RFC, but seems to be supported by several This downloads the headers of message number \var{msgid}. It
servers. returns the headers in the same format as \ex{pop3-retrieve-message}.
\end{defundesc} \end{desc}
\begin{defundesc}{pop3-delete}{connection msgid}{status} \defun{pop3-last}{connection}{msgid}
Mark message number \semvar{msgid} for deletion. The message will \begin{desc}
This returns 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{desc}
\defun{pop3-delete}{connection msgid}{undefined}
\begin{desc}
This mark message number \var{msgid} for deletion. The message will
not be deleted until the client logs out. not be deleted until the client logs out.
\end{defundesc} \end{desc}
\begin{defundesc}{pop3-reset}{connection}{status} \defund{pop3-reset}{connection}{undefined}
Any messages which have been marked for deletion are unmarked. \begin{desc}
\end{defundesc} This marks any messages which have been marked for deletion.
\end{desc}
\begin{defundesc}{pop3-quit}{connection}{status} \begin{desc}{pop3-quit}{connection}{undefined}
Close the connection with the mailhost. This closes the connection with the mailhost.
\end{defundesc} \end{desc}
\subsubsection*{Obsolete procedures} \defun{pop3-error?}{thing}{boolean}
\begin{desc}
Names in further versions of \ex{pop3} contained a colon (`\ex{:}') This returns \sharpt{} if \var{thing} is a \ex{pop3-error} object,
after the prefix `\ex{pop3-}'. This is now changed to a hyphen otherwise \sharpf.
('\ex{-}'), accordingly to SUnet's philosophy. If you need the old \end{desc}
names, use the \ex{pop3\=obsolete}-package that maps the old names to
the new ones.
\section{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: %%% Local Variables:
%%% mode: latex %%% mode: latex