From be87dc978e6f8e3ced358153043bc945eeca7d4e Mon Sep 17 00:00:00 2001 From: sperber Date: Tue, 21 Jan 2003 08:49:18 +0000 Subject: [PATCH] Reasonably complete and up-to-date docs for POP3. --- doc/latex/pop3.tex | 165 +++++++++++++++++++-------------------------- 1 file changed, 71 insertions(+), 94 deletions(-) diff --git a/doc/latex/pop3.tex b/doc/latex/pop3.tex index 199f119..6ade05c 100644 --- a/doc/latex/pop3.tex +++ b/doc/latex/pop3.tex @@ -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 \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. -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 -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. +server. This method avoids sending sensitive information over the +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. + + \ex{Pop3-connect} returns a value representing the connection to the + POP3 server, to be used in the procedures below. +\end{desc} -\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} - -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