/* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * 
 * ========================================================================
 */

		   c-client Driver Characteristics
			     Mark Crispin
			   11 December 2006


     Drivers are code modules that support different mailbox storage
technologies.  A mailbox storage technology may be implemented by
 1) files and directories on the local system
 2) a database
 3) a network protocol.

     In the case of files and directories on the local system, a
driver supports a particular mailbox format.  Mailbox formats are
discussed in more detail in the file formats.txt.

     As of the date this document was written, there was no bundled
support for any databases in c-client.  However, it should not be
particularly difficult to write a driver that communicates with a
database.

     Network protocols supported by c-client drivers are the Internet
Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and
IMAP2); the Post Office Protocol (version 3); and the Network News
Transport Protocol (NNTP).  In addition, c-client also supports NNTP
and the Simple Mail Transport Protocol (SMTP) for mailbox transport.

     By default, all drivers are enabled.  There is little benefit to
be gained by disabling a driver, with one exception.  The mbox driver
implements the behavior of automatically moving new mail from the
spool directory to the "mbox" file on the user's home directory, if
and *only* if the "mbox" exists and is in mailbox format.  The mbox
driver is listed under EXTRADRIVERS; if you wish to disable it just
remove it from that list and rebuild.

I. Special name "INBOX"

The following rules to select INBOX and its format apply in
the order given if "black box mode" is not in effect:
 1) mbox format is selected if file ~/mbox exists, and is in unix
    format or is zero-length.
 2) mx format is selected if file ~/INBOX/.mxindex exists.
 3) mbx format is selected if file ~/INBOX exists and is in mbx format.
 4) tenex format is selected if:
    a) file ~/mail.txt exists, and is in tenex format or is zero-length.
    b) file ~/INBOX exists and is in tenex format.
 5) mtx format is selected if:
    a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length.
    b) file ~/INBOX exists and is in mtx format.
 6) mmdf format is selected if the spool directory file exists and is
    in mmdf format.
 7) unix format is selected if the spool directory file exists and is
    in unix format.   
 8) the dummy driver is selected if the spool directory file does not
    exist, or exists and is empty.

If "black box mode" is not in effect, messages are automatically
transferred ("snarfed") from the spool directory to an INBOX in mbox,
mx, mbx, tenex, and mtx formats.

The following rules to select INBOX and its format apply in the order
given if "black box mode" is in effect:
 1) mx format is selected if file ~/INBOX/.mxindex exists.
 2) mbx format is selected if file ~/INBOX exists and is in mbx format.
 3) tenex format is selected if file ~/INBOX exists and is in tenex format.
 4) mtx format is selected if file ~/INBOX exists and is in mtx format.
 5) mmdf format is selected if file ~/INBOX exists and is in mmdf format.
 6) unix format is selected if file ~/INBOX exists and is in unix format.
 7) the dummy driver is selected if ~/INBOX does not exist, or exists
    and is empty.

II. Special Name #mhinbox

#mhinbox always refers to the directory "inbox" in the MH path, which
is declared in the ~/.mh_profile file.  Messages are automatically
transferred from the spool directory to #mhinbox mailbox.


III. Special Prefix "#mh/"

Any name prefixed with "#mh/" always refers to a directory in the MH
path, which is declared in the ~/.mh_profile file.  For example, the name
"#mh/foo" refers to directory "foo" in the MH path.


IV. Special prefix "#news."

Any name prefixed with "#news" always refers to a newsgroup.  For
example, the name "#news.comp.mail.misc" refers to newsgroup
"comp.mail.misc".


V. All Other Names

The driver is selected by generating a file name from the mailbox
name, and then examining the data of the object with the resulting
name.  The formats are checked in order: mx, mbx, tenex, mtx, mmdf,
unix, and phile.  The dummy driver is selected if the file is empty.

The file name is generated according to certain rules, based upon the
prefix of the mailbox name.  On UNIX, the following rules apply:

Prefix		Interpretation of Suffix
------		------------------------
/		[black box] preceeds a user name; "/foo/bar" means
		 "black box user foo's mailbox bar"
		[not black box] preceeds an absolute path name.
~		[not black box] preceeds a user name; "~foo/bar" means
		 "UNIX user foo's mailbox bar"
#ftp/		preceeds UNIX user ftp's mailbox name
#public/	preceeds UNIX user imappublic's mailbox name
#shared/	preceeds UNIX user imapshared's mailbox name

All other names are interpreted in the context of the UNIX user's home
directory (not black box), the black box user's black box directory
(black box), or UNIX user ftp's home directory (anonymous).

The strings "..", "//", and /~ are forbidden in names in:
 black box mode
 #ftp, #public, or #shared names
 anonymous users

Anonymous users may only access:
 INBOX (belonging to UNIX user ftp)
 files in or below UNIX user ftp's home directory
 #ftp, #news, and #public namespace

VI. Driver Comparison

The following information about the local file drivers is an
elaboration of a table compiled by Osma Ahvenlampi.

Driver	CA	CE	UID	Kwd	Sub	NFS	Performance	Layout
------	--	--	---	---	---	---	-----------	------
unix	no	no	yes	yes	no	limited	fair		file
 ;;; traditional UNIX format
mbox	no	no	yes	yes	no	limited	fair		file
 ;;; traditional UNIX format, INBOX only, using ~/mbox with automatic
 ;;; moving from the mail spool directory.
mmdf	no	no	yes	yes	no	limited	fair		file
 ;;; default on SCO systems
mbx	yes	yes	yes	yes	no	no	very good	prefile
 ;;; best performing local file driver; preferred format at UW
tenex	yes	no	no	limited	no	no	good		prefile
 ;;; compatible with UNIX MM
mtx	yes	no	no	limited	no	no	very good	prefile
 ;;; PC Pine standard format; compatible with TOPS-20; identical to tenex
 ;;; but instead CRLF newlines instead of LF
mx	yes	buggy	yes	yes	yes	no	poor		ixdir
 ;;; fullest function; *not* recommended due to performance problems and bugs;
 ;;; to be redesigned/rewritten
mh	yes	no	no	no	yes	yes	very poor	dir
 ;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names
news	yes	no	yes	no	yes	yes	very poor	ixdir
 ;;; local news spool access; #news. prefix for all names
phile	no	no	no	no	no	yes	good		file
 ;;; reads arbitrary file as a single readonly message

IMPORTANT: the "performance" ratings are relative to other drivers,
and not necessarily to other software which implements those formats.
They relate to the driver's performance in typical operations such as
an IMAP "FETCH ALL".

Key to headings:
	CA:	concurrent read/write access
	CE:	expunge permitted in concurrent read/write access
	UID:	sticky UIDs
	Kwd:	keyword flags
	Sub:	subfolders
	NFS:	usable over network filesystems (NFS, AFS, etc.)
	Layout:	file - single file
		prefile - file with preallocated space for state
		dir - directory, messages are files
		ixdir - directory, messages are files, with helper index

In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and
POP3 protocols respectively.