Documentation of C-client Functions and Interfaces

			     Mark Crispin
			 Revised 18 June 1992

			     Introduction

     The C-client API was originally written at Stanford University as
a set of routines to support IMAP and SMTP from a main program which
would handle the user interface.  A sample main program which uses the
C-client, MTEST.C, has run on a wide variety of platforms including
Unix, TOPS-20, Macintosh, and MS-DOS.

     This is a major redesign of the original C-client by the original
author, made at the University of Washington.  It uses ANSI C calling
conventions throughout to assist in function argument type checking.
It also provides the capability of having multiple means of accessing
mail through the user of "drivers"; consequently, in addition to
supporting IMAP it also supports Berkeley (/usr/spool/mail), Tenex
(mail.txt), mbox, mh, and netnews.  A future version of the C-client
will probably convert the current direct usage of SMTP to a driver as
well.

     C-client also supports MIME, the Internet Proposed Standard for
multi-part typed message bodies.

     The most important file for the author of an application using
the C-client is MAIL.H.  MAIL.H defines several important structures
of data which are passed between the main program and the C-client.
Although some functions (e.g. mail_fetchtext()) return the data
fetched as a convenience, for some data items (e.g. flags) you need to
get the data as a structure reference.  MAIL.H also defines a number
of useful constants.

     It should be noted that when MAIL functions exist to reference
data they should be used in preference to referencing the structures
directly.  This is because in some cases the data is not actually
fetched until a reference (via the function call) is made.  For
example, although the MESSAGECACHE item for a message can be obtained
by indexing the proper cache element in the stream, there is no
guarantee that the item in fact exists unless mail_fetchstructure() is
called for that message.  Less costly functions, mail_fetchfast() and
mail_fetchflags(), also exist to create and load a MESSAGECACHE item,
but their usage is not recommended except in particular circumstances.

     The main program will probably also need to include SMTP.H,
MISC.H, and OSDEP.H, but this usage should be solely to receive
function prototypes.  Any other definitions in those files should be
considered private to that module.

		       I. Public interface

     The files listed in this section are the standard C-client
mailsystem library modules, and are operating system and machine
independent.  Only those functions suitable for external callers are
documented here; other functions are for internal use only and are
used by external callers at their own risk!

[MAIL.C]:	Mail Access functions

[Note!!  There is an important difference between a "sequence" and a
 "msgno".  A sequence is a string representing one or more messages in
 IMAP2-style sequence format ("n", "n:m", or combination of these delimited
 by commas), whereas a msgno is an int representing a single message.]

void mail_link (DRIVER *driver)
 This function adds the specified driver to the list of mail drivers.
Initially there are no drivers, so all programs which intend to use
the MAIL routines need to have at least one call to this function.  A
function which uses IMAP2 would have a statement such as:
  mail_link (&imapdriver);	/* link in IMAP driver */
early in the program's initialization.

void mail_find (MAILSTREAM *stream,char *pat);
 This function finds known mailboxes that match the given wildcard
pattern.  The application's mm_mailbox() function is called for each
matching mailbox.

void mail_find_bboards (MAILSTREAM *stream,char *pat);
 This function finds known bboards that match the given wildcard
pattern.  The application's mm_bboard() function is called for each
matching mailbox.

MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options)
 This function opens the mailbox and if successful returns a stream
suitable for use by the other MAIL functions.  If oldstream is
non-NIL, an attempt is made to reuse oldstream as the stream for this
mailbox.  The options are a bit mask with one or more of the following:
	OP_DEBUG	Log IMAP protocol telemetry through mm_debug()
	OP_READONLY	Open mailbox read-only.
	OP_ANONYMOUS	Don't use or update a .newsrc file for news.
	OP_SHORTCACHE	Don't cache envelopes or body structures
	OP_SILENT	Don't pass mailbox events (internal use only)
 NIL is returned if this function fails for any reason.

MAILSTREAM *mail_close (MAILSTREAM *stream)
 This function closes the MAIL stream and frees all resources
associated with it that it may have created (subject to any handles
existing).
 This function always returns NIL, so it can be used as:
	stream = mail_close (stream);

MAILHANDLE *mail_makehandle (MAILSTREAM *stream)
 This function creates and returns a handle to the stream, suitable
for use as a secondary copy of the stream.  This is useful when some
entity that wishes to access the stream may survive the stream without
knowing that it outlived it.  For example, an object reading a message
may have a handle to a stream, but the message selection object that
spawned it (and which owns the stream) may have gone away.  A stream
can be closed or recycled while handles are pointing at it, but it is
not completely freed until all handles are gone.  A stream may have an
arbitrary number of handles.

void mail_free_handle (MAILHANDLE **handle)
 This function frees the handle and notifies the stream that it has
one fewer handle.  If this is the last handle on the stream and the
stream has been closed, then the stream is freed.

MAILSTREAM *mail_stream (MAILHANDLE *handle)
 This function returns the stream associated with the handle if and
only if the stream still represents the same MAIL connection associated
with the handle.  Otherwise, NIL is returned (meaning that there is no
active stream associated with this handle).

void mail_fetchfast (MAILSTREAM *stream,char *sequence)
 This function causes a cache load of all the "fast" information
(internal date, RFC 822 size, and flags) for the given sequence.
Since all this information is also fetched by mail_fetchstructure(),
this function is generally not used unless the OP_SHORTCACHE option
in the mail_open() call is used.

void mail_fetchflags (MAILSTREAM *stream,char *sequence)
 This function causes a fetch of the flags for the given sequence.
This main reason for using this function is to update the flags in the
local cache in case some other process changed the flags (multiple
simultaneous write access is allowed to the flags) as part of a "check
entire mailbox" (as opposed to "check for new messages") operation.

ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,long msgno,BODY **body)
 This function causes a fetch of all the information (envelope,
internal date, RFC 822 size, flags, and body structure) for the given
msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a parameter in
IMAP2.H) subsequent messages which are not yet in the cache.  No fetch
is done if the envelope for the given msgno is already in the cache.
The ENVELOPE and the BODY for this msgno is returned.  It is possible
for the BODY to be NIL, in which case no information is available about
the structure of the message body.
 This is the primary function for fetching non-text information about
messages, and should be called before any attempt to reference cache
information about this message via mail_elt().

char *mail_fetchheader (MAILSTREAM *stream,long msgno)
 This function causes a fetch of the complete, unfiltered RFC 822
format header of the specified message as a text string and returns
that text string.
 This function always returns a valid string pointer; if no header
exists or if it can not be fetched (e.g. by a deceased IMAP stream)
an empty string is returned.

char *mail_fetchtext (MAILSTREAM *stream,long msgno)
 This function causes a fetch of the non-header text of the specified
message as a text string and returns that text string.  No attempt is
made to segregate individual body parts.
 This function always returns a valid string pointer; if no header
exists or if it can not be fetched (e.g. by a deceased IMAP stream)
an empty string is returned.

char *mail_fetchbody (MAILSTREAM *stream,long m,char *sec,unsigned long *len)
 This function causes a fetch of the particular section of the body of
the specified message as a text string and returns that text string.
The section specification is a string of integers delimited by period
which index into a body part list as per the IMAP2bis document.  The
length of the body part, which may not necessarily be null-terminated,
is returned in len.  Body parts are not decoded by this function; see
rfc822_base64() and rfc822_quotedprintable().
 This function may return NIL on error.

void mail_fetchfrom (char *s,MAILSTREAM *stream,long msgno,long length)
 This function writes a "from" string of the specified length for the
specified message, suitable for display to the user in a menu line,
into the string pointed to by s.
 If the personal name of the first address in the envelope's from item
is non-NIL, it is used; otherwise a string is created by appending the
mailbox of the first address, an "@", and the host of the first
address.  The string is trimmed or padded with trailing spaces as
necessary to make its length match what the caller requested.
 The length argument is provided to make it convenient for the
application to decide upon the length it wants.  The string s must, of
course, be at least of this length.

void mail_fetchsubject (char *s,MAILSTREAM *stream,long msgno,long length)
 This function returns a "subject" string of the specified length for
the specified message, suitable for display to the user in a menu
line.
 The envelope's subject item is copied and trimmed as necessary to
make its length be no more what the caller requested.  Unlike
mail_fetchfromstring(), this function can return a string of shorter
length than what the caller requested.
 The length argument is provided to make it convenient for the
application to decide upon the length it wants.  The string s must, of
course, be at least of this length.

LONGCACHE *mail_lelt (MAILSTREAM *stream,long msgno)
 This function returns a `long' cache entry, consisting of an elt (as
a structure, not a poiner), an envelope pointer, and a body pointer.
This is generally used in conjunction with the elt lock count
functionality, to allow an application to associate the cached data of
a message with an open window independent of subsequent C-client
operations.  It is therefore only needed by sophisticated applications.
 Although this function will create a cache entry if it does not
already exist, that functionality is for internal use only.  This
function should never be called without having first called
mail_fetchfast() or mail_fetchstructure() on the message first.

MESSAGECACHE *mail_elt (MAILSTREAM *stream,long msgno)
 This function returns the cache entry for the specified message.
 Although this function will create a cache entry if it does not
already exist, that functionality is for internal use only.  This
function should never be called without having first called
mail_fetchfast() or mail_fetchstructure() on the message first.

void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag)
 This function causes a store to add the specified flag to the flags
set for the messages in the specified sequence.  If there is any
problem in setting flags, a message will be passed to the application
via the mm_log() facility.

void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag)
 This function causes a store to delete the specified flag from the
flags set for the messages in the specified sequence.  If there is any
problem in clearing flags, a message will be passed to the application
via the mm_log() facility.

void mail_search (MAILSTREAM *stream,char *criteria)
 This function causes a mailbox search using the specified criteria
(in IMAP2 format).  The application's mm_searched() function is called
for each message that matches the search criteria.  If there is any
problem in searching, a message will be passed to the application via
the mm_log() facility.

long mail_ping (MAILSTREAM *stream)
 The function pings the stream to see if it is still active.  It may
cause an "implicit check" for new mail.  It returns T if the stream is
still alive, NIL otherwise.

void mail_check (MAILSTREAM *stream)
 This function causes an explicit check of the mailbox for new
messages including a remote reparse of all flags in the mailbox.  The
application's mm_exists() function is called with the number of
messages in the mailbox.  The status of the check is passed to the
application via the mm_log() facility.
 Note that mail_fetchflags() needs to be called to update the flags in
the local cache if there was a remote change.

void mail_expunge (MAILSTREAM *stream)
 This function causes an expunge of the mailbox.  The application's
mm_expunged() function is called for each message that has been
expunged.  The application's mm_exists() function is called at the
start and end of the expunge to ensure synchronization.  The status of
the expunge is passed to the application via the mm_log() facility.
 Note that the decrementing of msgno's for subsequent messages happens
immediately; for example, if three consequtive messages starting at
msgno 5 are expunged, mm_expunged() will be called with a msgno of 5
three times.

long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox)
 This function causes the messages in the specified sequence to be
copied to the specified mailbox.  The system \Seen flag is set for
these messages and T is returned if the copy is successful.
 If there is any problem in copying, a message will be passed to the
application via the mm_log() facility and the function returns NIL.
No copying is actually done in this case.
 Note that the mailbox must be on the same host as the stream and is a
mailbox of the type of the source mailbox only.

long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox)
 This function causes the messages in the specified sequence to be
copied to the specified mailbox.  The system \Seen and \Deleted flags
are set for these messages and T is returned if the copy is successful.
 If there is any problem in copying, a message will be passed to the
application via the mm_log() facility and the function returns NIL.  No
moving is actually done in this case.
 Note that the mailbox must be on the same host as the stream and is a
mailbox of the type of the source mailbox only.

void mail_gc (MAILSTREAM *stream,long gcflags)
 This function purges the cache of entries of a specific type.  Some
drivers do not allow purging of particular cache types, and an attempt
to do so is ignored.  The gcflags argument is a bit mask composed of
the following values:
	GC_ELT		message cache elements (IMAP2 driver only)
	GC_ENV		ENVELOPEs and BODYs
	GC_TEXTS	cached texts (IMAP2, MH, and NEWS drivers only)

char *mail_date (char *string,MESSAGECACHE *elt)
 This function writes into string a date/time in the form
	dd-mmm-yyyy hh:mm:ss +zzzz
based based upon the data in the elt.  The string must be large enough
to hold this string.

long mail_parse_date (MESSAGECACHE *elt,char *string);
 This function parses the date/time stored in the given string and
stores the result of the parse in the elt.  If the parse is successful,
T is returned, else NIL.

void mail_debug (MAILSTREAM *stream)
 This function enables telemetry logging for this stream.  All
telemetry is passed to the application via the mm_dlog() facility.

void mail_nodebug (MAILSTREAM *stream)
 This function disables telemetry logging for this stream.

ENVELOPE *mail_newenvelope ()
 This function returns a new, empty envelope.

ADDRESS *mail_newaddr ()
 This function returns a new, empty address.

BODY *mail_newbody ()
 This function returns a new, empty body.

PARAMETER *mail_newbody_parameter ()
 This function returns a new, empty body parameter.

PART *mail_newbody_part ()
 This function returns a new, empty body part.

void mail_free_body (BODY **body)
 This function frees a body and all its contents.

void mail_free_body_parameter (PARAMETER **parameter)
 This function frees a body parameter and all its contents.

void mail_free_body_part (PART **part)
 This function frees a body part and all its contents.

void mail_free_elt (MESSAGECACHE **elt)
 This function frees a cache element.  Normally, this is used only if
the main program has a private pointer to cache elements.  If so, it
is expected to increment the cache element's lockcount when it makes a
private pointer, and to call this function when it is finished with it.

void mail_free_lelt (LONGCACHE **lelt)
 This function frees a long cache element.  Normally, this is used only if
the main program has a private pointer to cache elements.  If so, it
is expected to increment the cache element's lockcount when it makes a
private pointer, and to call this function when it is finished with it.

void mail_free_envelope (ENVELOPE **env)
 This function frees an envelope and all its contents.

void mail_free_address (ADDRESS **address)
 This function frees an address and all its contents.

[MISC.C]:	Miscellaneous utility functions

char *ucase (char *string)
 This function converts each lowercase character of the specified
string to uppercase and returns the string.

char *lcase (char *string)
 This function converts each uppercase character of the specified
string to lowercase and returns the string.

char *cpystr (char *string);
 This function returns a copy of the string.

long find_rightmost_bit (long *valptr)
 This function returns -1 if the 32-bit value pointed to by valptr is
non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of
the right-most bit in that value.  This is used to convert from the
bits in the cache's userFlags item to an index into the stream's
userFlags array of flag texts.

long min (long i,long j)
 This function returns the minimum of the two integers.

long max (long i,long j)
 This function returns the maximum of the two integers.

long search (char *s,long c,char *pat,long patc)
 This function does a fast case-independent search for the given
pattern in pat (lenth patc) in base string s, and returns T if the
pattern is found in the string.

long pmatch (char *s,char *pat)
 This function returns T if the given wildcard pattern matches the
string in s.  Otherwise NIL is returned.

[SMTP.C]:	Mail Transfer Protocol functions

SMTPSTREAM *smtp_open (char **hostlist,long debug)
 This function opens an MTP connection to a one of the hosts in the
host list and if successful returns a stream suitable for use by the
other MTP functions.  The hosts are tried in order until a connection
is successfully opened.  If debug is non-NIL, mtp_debug() is called on
the stream immediately after the TCP connection is opened so that the
greeting and hello protocol goes into the debugging telemetry.  NIL is
returned if this function fails to open a connection to any of the
hosts in the list.

void smtp_close (SMTPSTREAM *stream)
 This function closes the MTP stream and frees all resources
associated with it that it may have created.

long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body)
 This function negotiates an MTP transaction of the specified type
(one of "MAIL", "SEND", "SAML", or "SOML") to deliver the specified
message.  This function returns T if success or NIL if there is any
failure.  The text reason for the failure is in the stream's reply
item; if it is associated with a recipient it is also in that address'
error item.

void mtp_debug (SMTPSTREAM *stream)
 This function enables SMTP protocol telemetry logging for this
stream.  All SMTP protocol operations are passed to the application
via the mm_dlog() facility.

void mtp_nodebug (SMTPSTREAM *stream)
 This function disables SMTP protocol telemetry logging for this
stream.

[RFC822.C]:	RFC 822 Protocol support functions

[Only the functions documented here should be used by application
 programs.]

void rfc822_header (char *header,ENVELOPE *env,BODY *body)
 This function writes an RFC 822 format header into header based on
the information in message.

void rfc822_write_address (char *destination,ADDRESS *address)
 This function writes an RFC 822 format address list into destination
based on the information in address and is therefore the inverse of
rfc822_parse_adrlist().

void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i,
		       STRING *b,char *host,char *tmp)
 This function parses the RFC 822 header pointed to by s with body
pointed to by stringstruct b into the specified destination
envelope and body pointers, using host as the default host name and
tmp as a scratch buffer.  This function is intended solely to support
header parsing for non-IMAP MAIL drivers.  Any parsing errors are
noted via the mm_log() mechanism.

void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host)
 This function parses the address list in the given string into an
address list in lst.  Any addresses missing a host name are have the
host name defaulted from the host argument.  If the destination list
is non-empty it appends the new addresses to the list.  Any parsing
errors are noted via the mm_log() mechanism.

long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,TCPSTREAM *s)
 This function writes the message described with the given envelope
and body, using the I/O function f and passing f the designator s.
The first argument, t, is a scratch buffer which must be large
enough to hold the message header.  T is returned if this function
succeeds, else NIL is returned.
 The function f is of the form:
  typedef long (*soutr_t) (void *stream,char *string);
where stream is intended to hold sufficient information to enable the
output routine to know where to output to, and the string is a null-
terminated string to output.  This function returns either T or NIL,
and that value is passed up to rfc822_output() for its return.

void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len)
 This function decodes a BASE64 body part given a source string and
its length.  The decoded body part as a sequence of binary bytes is
returned, and its length is returned in len.

char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len)
 This function decodes a Quoted-Printable body part given a source
string and its length.  The decoded body part as an 8-bit character
string is returned, and its length is returned in len.

		     II. Main program co-routines

     All main programs which use the C-client must have the following
service co-routines:

[Main program]

#include "mail.h"
#include "smtp.h"
#include "misc.h"
#include "osdep.h"

void mm_searched (MAILSTREAM *stream,long number)
 This function is called from mail_search to notify the main program
that this message number matches the search.  Note that the stream is
locked and that therefore you cannot call any mail_xxx functions!

void mm_exists (MAILSTREAM *stream,long number)
 This function is called from several functions to notify the main
program that there are this many messages in the mailbox.  It is also
used to notify the main program of new mail, by announcing a higher
number than the main program was previously aware.  Note that the
stream is locked and that therefore you cannot call any mail_xxx
functions!

void mm_expunged (MAILSTREAM *stream,long number)
 This function is called from mail_expunge to notify the main program
that this message number has been expunged from the mail file and that
all subsequent messages are now referenced by a message number one
less than before.  This implicitly decrements the number of messages
in the mailbox.  Note that the stream is locked and that therefore you
cannot call any mail_xxx functions!

void mm_mailbox (char *string)
 This function is called from mail_find to notify the main program
that this mailbox matches the find request.  Note that the stream is
locked and that therefore you cannot call any mail_xxx functions!

void mm_bboard (char *string)
 This function is called from mail_find_bboards to notify the main
program that this bboard matches the find request.  Note that the
stream is locked and that therefore you cannot call any mail_xxx
functions!

void mm_notify (MAILSTREAM *stream,char *string,long errflg)
 This function is called when an unsolicited response of type OK, NO,
or BAD from a remote IMAP server is received.  No newline is included
in the string, so this function has to output its own.  The IMAP
protocol defines this facility as a means for the server to transmit
text for the end user to see.  Although the behavior of all possible
IMAP server implementations can not be predicted, the following
general assumptions can be made about the value of errflg and how it
relates to the text based on how the C-client based IMAP server
behaves:
 NIL	normal operation.  The text is `babble' that the server
	thinks may be interesting to the user.  Examples: the
	greeting message from the server, notice of enabling of the
	kludge to support MacMS, error in parsing the header of a
	message in the remote mailbox (a C-client PARSE mm_log()
	event).  Display of these messages to the user is optional.
 WARN	A C-client WARN mm_log() event which occurred in the server.
	See mm_log() documentation below.  This is also called from
	the Berkeley mail driver if the requested mailbox write
	operation failed because the main program returned NIL from
	a "non-serious" mm_diskerror() call.
 ERROR	An unknown IMAP protocol error, or an extremely serious
	internal error.  These are supposedly impossible in debugged
	software, and so should be called to the attention of the user
	and/or support staff.  Whatever happened has probably already
	disrupted the user's work, so it is alright to deal with this
	in a modal fashion.
Note that usually the stream is locked and that therefore you cannot
call any mail_xxx functions!

void mm_log (char *string,long errflg)
 This function is called on various C-client events.  No newline is
included in the string, so this function has to output its own.  In
general, it is intended that these be messages for the user to see.
The value of errflg indicates the urgency of these messages, as
follows:
 NIL	normal operation.  The text is `babble' that the C-client
	thinks may be interesting to the user.  Typically, these are
	acknowledgement texts from various operations ("Expunged 3
	messages", "Re-using connection", "Connection closing") which
	may contain useful information.  Display of these messages to
	the user is optional depending upon the needs of the
	application.
 PARSE	an error occurred in RFC 822 parsing.  Since bogus headers are
	an all-too-common occurrence in the real word, these can often
	be ignored on the GIGO principle.  However, it may be a good
	idea to report these errors if calling the rfc822 routines as
	part of command parsing e.g. mtp_parse_address().
 WARN	an error condition occurred that did not abort the requested
	operation, or which has a well-defined "right thing to do"
	when it happens.  This can be things such as "Can't open
	mailbox for read-write, so opening read-only", "Empty
	mailbox", "Login failed, try again", "Waiting for mailbox to
	become unlocked", etc.  Warnings can also occur if the abort
	option is taken from mm_diskerror() to verify that the abort
	has taken place.  Furthermore, it can occur (in massive
	quantities!) in the event of a C-client detected IMAP
	protocol error; but this should never happen in debugged
	software.  Warnings should be called to the user's attention,
	but probably should not interrupt the flow of the user's work
	(that is, it's alright to display warnings in a view area
	without waiting for any user acknowledgement of seeing the
	warning).  It is not, however, absolutely necessary for an
	application to display warnings.
 ERROR	a serious error condition occured that aborted the requested
	operation and possibly also aborted the mail stream.  This
	ranges from normal error conditions such as "Can't open
	mailbox", "too many login failures, go away" to bizarre
	conditions such as "Apparent new mail appeared in the mailbox
	that doesn't look like mail, program aborting".  Errors must
	be called to the user's attention, and probably should require
	some sort of acknowledgement (e.g. answering a modal panel)
	before the application proceeds.
Note that usually the stream is locked and that therefore you cannot
call any mail_xxx functions!

void mm_dlog (char *string)
 This function is called from several functions to output a string to
a debugging telemetry stream.  No newline is included in the string,
so this function has to output its own.  This is called only when
debugging is enabled on the stream in question.  Note that usually the
stream is locked and that therefore you cannot call any mail_xxx
functions!

void mm_login (char *host,char *user,char *pwd,long trial)
 This function is called to get a user name and password for the given
host.  The function stores the user name and password in the strings
pointed to by the appropriate arguments.  The trial argument is the
number of attempts to perform the login and is initially zero (e.g.
for a default username and password login functionality).  It is
incremented for each subsequent trial until the maximum number of
trials are made.  Note that the stream is locked and that therefore
you cannot call any mail_xxx functions!

void mm_critical (MAILSTREAM *stream)
 This function is called to alert the application that the C-client is
about to run some critical code that may result in a clobbered mail
file if it is interrupted.  Note that the stream is locked and that
therefore you cannot call any mail_xxx functions!

void mm_nocritical (MAILSTREAM *stream)
 This function is called to alert the application that the C-client is
no longer running critical code that may result in a clobbered mail
file if it is interrupted.  Note that the stream is locked and that
therefore you cannot call any mail_xxx functions!

long mm_diskerror (MAILSTREAM *stream,long errcode,long serious)
 This function is called to alert the application that the C-client
has encountered an unrecoverable write error when trying to update the
mail file.  errcode contains the system error code.  If serious is
non-zero, then it is probable that the disk copy of the mailbox has
been damaged.  The return value from this function is the abort flag;
if serious is zero and the abort flag is non-zero, the operation is
aborted.  If the abort flag is zero or if serious was non-zero, a
return from this function will retry the failing operation.

void mm_fatal (char *string)
 This function is called from the fatal() routine in the operating
system code to notify the main program that it is about to crash.  The
string contains a reason.  At the very minimum, the main program
should do something like
 mm_log (string,ERROR);
and then return.  No newline is included in the string, so this
function has to output its own.

			* * * IMPORTANT * * *

  Any multi-tasking application should test stream->lock prior to
calling any functions in this module.  Any attempt to do a mail_*
operation while one is already in progress on the same stream will
cause the application to fail in unpredictable ways, mostly likely due
to the _exit() calls in the internal mail_lock() routine when it
discovers the stream is already locked.

 Note that this check is insufficient in a preemptive-scheduling
multi-tasking application due to the possibility of a timing race.
Such applications must be written so that only one process accesses
the stream, or to have a higher level lock.

 Since MAIL operations will not finish until they are completed, a
single-tasking application does not have to worry about this problem,
except in the co-routines invoked from MAIL (e.g. mm_exists(), etc.)
in which case the stream is *always* locked.


	   III. Operating system-dependent public interface

     The files listed below must be rewritten for each port of the
C-client to a new operating system.

[OSDEP.C]:	operating system-dependent functions

#include "mail.h"
#include "osdep.h"

void rfc822_date (char *date)
 This function is called to get the current date and time in an RFC 822
format string into the string pointed to by the argument.

void *fs_get (size_t size)
 This function allocates and returns a block of free storage of the
specified size.  Unlike malloc(), there is no failure return; this
function must return with the requested storage.

void fs_resize (void **block,size_t size)
 This function resizes the free storage block, updating the pointer if
necessary.  Unlike realloc(), there is no failure return; this
function must return with the requested storage.

void fs_give (void **block)
 This function releases a block of free storage allocated by fs_get()
and zeros the block pointer.

void fatal (char *string)
 This function is called when an "impossible" error is detected and the
client wishes to crash.  The string argument contains a reason string.

char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl)
 This function is called to copy into a destination string dst of size
dstl (resized if necessary), a CRLF newline form string from local
format string src of size srcl.

TCPSTREAM *tcp_open (char *host,long port)
 This function is called to open a TCP connection to the given host
name on the given port number.  It returns a TCPSTREAM, which is an
internal data structure for this file and is implementation-dependent.
NIL is returned if this function fails for any reason.

TCPSTREAM *tcp_aopen (char *host,char *service)
 This function is called to open a connection to the given host name
with the given service name.  At the present time, that service name
is a Unix-format pathname (/etc/rimapd).  This function is expected to
return a TCPSTREAM only if the connection was open and the user has
been authenticated through an external mechanism such as the Unix r??
protocols.

char *tcp_getline (TCPSTREAM *stream)
 This function returns an fs_get() string containing a null-terminated
text line from the TCP stream.  The CR/LF which terminated the line is
not included.  The caller should free() the string when it is finished
with it.  NIL is returned if this function fails for any reason.

long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer)
 This function reads the requested number of bytes into the indicated
buffer.  This function returns T if successful and NIL if it fails for
any reason.

long tcp_soutr (TCPSTREAM *stream,char *string)
 This function writes the indicated (null-terminated) string to the
TCP stream.  This function returns T if successful and NIL if it fails
for any reason.

void tcp_close (TCPSTREAM *stream)
 The function closes the TCP stream and frees all resources associated
with it that it may have created.

char *tcp_host (TCPSTREAM *stream)
 This function returns the stream's foreign host name string.

char *tcp_localhost (TCPSTREAM *stream)
 This function returns the stream's local host name string.

			 IV. Driver interface

     When writing a new driver for the C-client, you must provide a
DRIVER stucture giving a dispatch vector between MAIL and the driver.
The DRIVER dispatch vector is described in MAIL.H.

[driver.C]:	driver for a particular mailbox type

#include "mail.h"
#include "driver.h"
#include "misc.h"
#include "osdep.h"

DRIVER *next;
 The first entry is a DRIVER * pointer to the next driver which this
application supports (or NIL if this is the last driver).  Drivers are
lunk together via the mail_link() function.  The remaining entries are
function pointers as follows

DRIVER *driver_valid (char *name)
 This function returns a pointer to the driver's DRIVER dispatch
vector iff this driver accepts the given name as a valid mailbox for
this driver.  Otherwise, it returns the value of the next driver's
driver_valid() or NIL if there is no next driver.  In other words,
calling driver_valid() for the first driver will return the driver
dispatch vector for the driver which supports this type of mailbox.

void driver_find (MAILSTREAM *stream,char *pat)
 This function implements mail_find() function for this driver.

void driver_find_bboard (MAILSTREAM *stream,char *pat);
 This function implements mail_find_bboard() function for this driver.

MAILSTREAM *driver_open (MAILSTREAM *stream)
 This function opens the mailbox identified by the given stream.  It
may use the data on the stream and create additional data on
stream->local as necessary.  It should return the given stream unless
it failed to open the mailbox, in which case it should return NIL.

void driver_close (MAILSTREAM *stream)
 This function implements mail_close() function for this driver.

void driver_fetchfast (MAILSTREAM *stream,char *sequence)
 This function implements mail_fetchfast() function for this driver.

void driver_fetchflags (MAILSTREAM *stream,char *sequence)
 This function implements mail_fetchflags() function for this driver.

ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,long msgno,BODY **body)
 This function implements mail_fetchstructure() function for this
driver.

char *driver_fetchheader (MAILSTREAM *stream,long msgno)
 This function implements mail_fetchheader() function for this driver.

char *driver_fetchtext (MAILSTREAM *stream,long msgno)
 This function implements mail_fetchtext() function for this driver.

char *driver_fetchbody (MAILSTREAM *stream,long msgno,char *section)
 This function implements mail_fetchbody() function for this driver.

void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag)
 This function implements mail_setflag() function for this driver.

void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag)
 This function implements mail_clearflag() function for this driver.

void driver_search (MAILSTREAM *stream,char *criteria)
 This function implements mail_search() function for this driver.

long driver_ping (MAILSTREAM *stream)
 This function implements mail_ping() function for this driver.

void driver_check (MAILSTREAM *stream)
 This function implements mail_check() function for this driver.

void driver_expunge (MAILSTREAM *stream)
 This function implements mail_expunge() function for this driver.

long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox)
 This function implements mail_copy() function for this driver.

long driver_move (MAILSTREAM *stream,char *sequence,char *mailbox)
 This function implements mail_move() function for this driver.

     Drivers may call all of the MAIL functions documented above plus
the following co-routine support functions:

void mail_searched (MAILSTREAM *stream,long msgno)
 This function is called by the driver to notify MAIL that this
message number matches a search.  It invokes the main program's
mm_searched() function.

void mail_exists (MAILSTREAM *stream,long nmsgs)
 This function is called by the driver to notify MAIL that this
message number exists (i.e. there are this many messages in the
mailbox).  It invokes the main program's mm_exists() function.

void mail_recent (MAILSTREAM *stream,long recent)
 This function is called by the driver to notify MAIL that this
many messages are "recent" (i.e. arrived in the mailbox since the
previous time the mailbox was opened).

void mail_expunged (MAILSTREAM *stream,long msgno)
 This function is called by the driver to notify MAIL that this
message number has been expunged from the mail file and that all
subsequent messages are no references by a message number one less
than before.  It invokes the main program's mm_expunged() function.

void mail_lock (MAILSTREAM *stream)
 This function sets the stream lock.  It is an error to set the stream
lock if the stream is already locked.
 This is mainly used to catch errors due to a co-routine function
(e.g. mm_exists) inadvertantly recursing back to the MAIL routines and
establishing an infinite recursion.  Normally, drivers will set the
lock prior to calling one of the co-routine functions above or, more
likely, in the beginning of the driver's non-reentrant "do operation"
section.  In the IMAP2 driver, the stream lock is set when entering
imap_send() and cleared on exit.

void mail_unlock (MAILSTREAM *stream)
 This function releases the stream lock.  It is an error to release
the stream lock if the stream is not locked.