Reasonably complete and up-to-date docs for POP3.
This commit is contained in:
sperber
parent
0cb68b88c9
commit
be87dc978e
|
|
@ -1,119 +1,96 @@
|
|||
\section{Using POP3}\label{cha:pop3}
|
||||
\chapter{Using POP3}\label{cha:pop3}
|
||||
%
|
||||
\begin{description}
|
||||
\item[Used files:] pop3.scm pop3-obsolete.scm
|
||||
\item[Name of the package:] pop3 pop3-obsolete.scm
|
||||
\end{description}
|
||||
%
|
||||
\section{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.
|
||||
The \ex{pop3} structure provides a client for the POP3 protocol that
|
||||
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 ISPs.
|
||||
|
||||
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
|
||||
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.
|
||||
network. Both methods are implemented by \ex{pop3}.
|
||||
|
||||
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.
|
||||
|
||||
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}
|
||||
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}
|
||||
\ex{Pop3-connect} returns a value representing the connection to the
|
||||
POP3 server, to be used in the procedures below.
|
||||
\end{desc}
|
||||
|
||||
In the further descriptions of the procedures, \semvar{connection}
|
||||
always refers to the result of \ex{pop3-\ob{}connect}.
|
||||
|
||||
\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
|
||||
\defun{pop3-stat}{connection}{number bytes}
|
||||
\begin{desc}
|
||||
This returns the number of messages and the number of bytes waiting in the
|
||||
maildrop.
|
||||
\end{defundesc}
|
||||
\end{desc}
|
||||
|
||||
\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}
|
||||
Most of the following procedures accept a \var{msgid} argument which
|
||||
specifies a message number, which ranges from 1 for the first message
|
||||
to the number returned by \ex{pop3-stat}.
|
||||
|
||||
\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}
|
||||
\defun{pop3-retrieve-message}{connection msgid}{headers message}
|
||||
\begin{desc}
|
||||
This downloads message number \var{msgid} from the mailhost.
|
||||
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}
|
||||
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}
|
||||
\defun{pop3-retrieve-headers}{connection msgid}{headers}
|
||||
\begin{desc}
|
||||
This downloads the headers of message number \var{msgid}. It
|
||||
returns the headers in the same format as \ex{pop3-retrieve-message}.
|
||||
\end{desc}
|
||||
|
||||
\begin{defundesc}{pop3-delete}{connection msgid}{status}
|
||||
Mark message number \semvar{msgid} for deletion. The message will
|
||||
\defun{pop3-last}{connection}{msgid}
|
||||
\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.
|
||||
\end{defundesc}
|
||||
\end{desc}
|
||||
|
||||
\begin{defundesc}{pop3-reset}{connection}{status}
|
||||
Any messages which have been marked for deletion are unmarked.
|
||||
\end{defundesc}
|
||||
\defund{pop3-reset}{connection}{undefined}
|
||||
\begin{desc}
|
||||
This marks any messages which have been marked for deletion.
|
||||
\end{desc}
|
||||
|
||||
\begin{defundesc}{pop3-quit}{connection}{status}
|
||||
Close the connection with the mailhost.
|
||||
\end{defundesc}
|
||||
\begin{desc}{pop3-quit}{connection}{undefined}
|
||||
This closes the connection with the mailhost.
|
||||
\end{desc}
|
||||
|
||||
\subsubsection*{Obsolete procedures}
|
||||
|
||||
Names in further versions of \ex{pop3} contained a colon (`\ex{:}')
|
||||
after the prefix `\ex{pop3-}'. This is now changed to a hyphen
|
||||
('\ex{-}'), accordingly to SUnet's philosophy. If you need the old
|
||||
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}
|
||||
\defun{pop3-error?}{thing}{boolean}
|
||||
\begin{desc}
|
||||
This returns \sharpt{} if \var{thing} is a \ex{pop3-error} object,
|
||||
otherwise \sharpf.
|
||||
\end{desc}
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
|
|
|
|||
Loading…
Reference in New Issue