internal.txt

Vovida 社区开源的 SIP 协议源码

	  Documentation of c-client Functions and Interfaces

REVISED: 19 August 1996

				  Credits

     The original version of this document was written by Mark Crispin at
the University of Washington, and described the version of c-client that
supported the IMAP2 (RFC 1176) and IMAP2bis (unpublished) protocols.

     This version is a substantial rewrite of that document, and was
written by Mark Crispin with funding from Sun Microsystems, Incorporated.
Sun's generous support of this work is gratefully acknowledged.


				 Road Map

     This document is organized into the following sections.  Except as
noted, an implementor of an application that uses c-client needs to be
familiar with all of these sections.  Someone who plans to write a new
mailbox driver for c-client (or otherwise modify it) needs to be familiar
with all sections, no exception.

History
	History of how c-client came about.

Overview
	Read this before designing an application that uses c-client.

c-client Structures
	Documentation of several important c-client structs which are
	used in, and returned by, c-client calls.

String Structures
	Documentation of the concept of a "string structure", which
	provides random access to strings without requiring that the
	string be in memory.

c-client Support Functions
	Documentation of support functions for c-client; these deal
	with c-client functionality.

	Only mail_parameters() is of interest to most application
	developers.  Advanced application developers, particularly
	for limited memory systems, may also need to know about the
	readfn_t, mailgets_t, mailcache_t, and tcptimeout_t function
	pointer types, and possibly also the mail_valid_net_parse()
	function.

Mailbox Access Functions
	Documentation of functions which deal with mailboxes;
	listing, subscribing, creating, deleting, renaming, status
	inquiries, opening, and closing mailboxes.

Handle Functions
	Documentation of mail stream handles, which provide protection
	for an advanced application which may have multiple pointers to
	a single mail stream.  If a stream has a handle on it, closing
	the stream does not release its memory, so pointers to it in
	the application remain valid.  Freeing the last handle will free
	the entire stream.

	This is only of interest for advanced application developers.

Message Data Fetching Functions
	Documentation on message data fetching in an open mailbox,
	including parsed representations of RFC-822 and MIME headers
	and message text.  Also how to fetch message attributes (flags,
	internal date, sizes).

Message Status Manipulation Functions
	Documentation on altering message flags in an open mailbox.

Mailbox Searching
	Documentation on searching an open mailbox for messages which
	match certain criteria (e.g. "messages sent July 4 from Jones
	with text `Paris'").

Miscellaneous Mailbox and Message Functions
	Documentation on other operations that would be used by an
	application but that don't fit into any of the above categories.

Date/Time Handling Functions
	Documentation on functions that deal with date/time strings.

	This is only of interest for advanced application developers
	and for implementors of new c-client drivers.

Utility Functions
	Documentation on internal utility functions.

	This is primarily of interest for implementors of new c-client
	drivers, but advanced application developers may also use some
	of these functions.

Data Structure Instantiation/Destruction functions
	Documentation on creating and destroy c-client structures.

	This is primarily of interest for implementors of new c-client
	drivers.  However, application developers will need some of
	these functions to create and destroy structures which are used
	as arguments to various application functions.

Authentication Functions
	Documentation on support for network protocol authentication
	functions.

	This is only of interest for implementors of new c-client
	drivers which deal with authentication mechanisms.

Network Access Functions
	Documentation on creating and destroy c-client structures.

	This is primarily of interest for implementors of new c-client
	drivers which deal with a network.  However, advanced
	application developers may need to use this information if they
	wish to insert their own layer into a network session.

Subscription Management Functions
	Documentation on managing the local (client-based) subscription
	database file.

	This is primarily of interest to advanced application developers.

Miscellaneous Utility Functions
	Documentation on various useful utility functions, such as "make
	a copy of this string."

SMTP Functions
	Documentation on posting email messages via SMTP protocol.

NNTP Functions
	Documentation on posting netnews messages via NNTP protocol.

RFC 822 Support Functions
	Documentation on public RFC-822/MIME functions.

	This is primarily of interest for implementors of new c-client
	drivers and advanced application developers.

Operating System-Dependent Public Interface
	Documentation on OS-dependent functions.  With the exception of
	fs_get(), fs_give(), and fs_resize(), which should be called
	instead of malloc(), free(), and realloc(), these functions are
	primarily of interest for implementors of new c-client drivers.

Main Program Callbacks
	Documentation of functions which the main program must provide
	as callbacks from c-client.

Driver Interface
	Documentation of the driver dispatch vector and the functions
	which a driver must supply.

	This is primarily of interest for implementors of new c-client
	drivers.

Driver Support Functions
	Documentation of support functions which are called by drivers.

	This is primarily of interest for implementors of new c-client
	drivers.
				  History

     The c-client API was originally written by Mark Crispin at Stanford
University as a set of routines to support IMAP and SMTP from a main
program which would handle the user interface.  In its original form, it
was written as the low-level routines that were to be used as part of a
Macintosh client.

     The first IMAP client, MM-D (for "MM on Xerox D machines" -- MM was a
popular DEC-20 mail program) was written in Interlisp for Xerox Lisp
machines.  At that time, there was no name for the embryonic Mac client,
but since it was the first one to be written in C instead of Lisp, it was
given a development name of "C client".  This name became "c-client"
because that is the name of the subdirectory on UNIX where the source files
were stored.

     To exercise the routines, a minimal main program which uses c-client,
mtest, was written.  mtest has subsequently been extended so that it runs
on every platform that c-client is ported.

     The real Mac client, was eventually written by Frank Gilmurrary and
Bill Yeager at Stanford using the autumn 1988 version of c-client and named
"MacMS".  In the winter of 1988-89, Mark Crispin, who had changed jobs to
the University of Washington, developed MS as an MM-like text-based program
for UNIX and MailManager as a GUI-based program for NeXT machines.

     The realization sunk in that this API needed its own name.  As early
as spring 1989, there were at least four programs (mtest, MS, MailManager,
and MacMS) that used it.  The name c-client thus became permanent.

     In its history, c-client has undergone two major redesigns, both by
Mark Crispin who is now on the staff at the University of Washington.

     The first major redesign added the following:
	1) ANSI C calling conventions throughout to assist in function
	   argument type checking.
	2) Vectoring mail access calls through "driver" methods; thus
	   providing transparent access to multiple types of mail
	   stores with the same call.
	3) MIME support.

     The second major redesign was part of the IMAP4 project.  Many
c-client functions were extended with additional arguments and options.
The driver interface was also made simpler, with more work done by
driver-independent code.

			       Overview

     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_body()) return the data
fetched, for certain other data items (e.g. flags) you need to get the
data as a structure reference.  mail.h also defines a large number of
useful constants and structures.

     When a function in mail.h exists to reference data, it MUST be
used instead of 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
element 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_full() is called for that message.
Less costly functions. also exist to create and load a MESSAGECACHE
element.

     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.

     Two important predefined symbols are NIL and T.  NIL is any sort
of "false"; T is any sort of "true".  NIL is also used to null-specify
certain optional arguments.

			* * * IMPORTANT * * *

     Any multi-threaded application should test stream->lock prior to
calling any c-client stream functions.  Any attempt to call a
mail_xxx() function while one is already in progress on the same
stream will cause the application to fail in unpredictable ways.

     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 callback invoked from MAIL (e.g. mm_exists(), etc.) in which
case the stream is *always* locked.

			  c-client Structures

     c-client has a large number of structures which are used for
multiple functions.  The most important of these are described here.

     The MAILSTREAM structure is used to reference open mailboxes.
Applications may reference the following:

char *mailbox;			mailbox name
unsigned short use;		stream use count, this is incremented
unsigned short sequence;	stream sequence, this is incremented
				 each time a stream is reused (i.e.
				 mail_open() is called to open a
				 different mailbox on this stream)
unsigned int rdonly : 1;	stream is open read-only
unsigned int anonymous : 1;	stream is open with anonymous access
unsigned int halfopen : 1;	stream is half-open; it can be
				 reopened or used for functions that
				 don't need a open mailbox such as
				 mail_create() but no message data
				 can be fetched
unsigned int perm_seen : 1;	Seen flag can be set permanently
unsigned int perm_deleted : 1;	Deleted flag can be set permanently
unsigned int perm_flagged : 1;	Flagged flag can be set permanently
unsigned int perm_answered :1;	Answered flag can be set permanently
unsigned int perm_draft : 1;	Draft flag can be set permanently
unsigned int kwd_create : 1;	new user flags can be created by
				 referencing then in mail_setflag() or
				 mail_clearflag().  Note: this can
				 change during a session (e.g. if
				 there is a limit on the number of
				 keywords), so check after creating a
				 new flag to see if any more can be
				 created before letting the user try
				 to do so
unsigned long perm_user_flags;	corresponding user flags can be set
				 permanently.  This is a bit mask
				 which matches the entries in
				 stream->user_flags[]
unsigned long gensym;		generated unique value.  Always
				 referenced with stream->gensys++
unsigned long nmsgs;		number of messages in current mailbox
unsigned long recent;		number of recent messages in current
				 mailbox
unsigned long uid_validity;	UID validity value; this is used to
				 verify that recorded UIDs match the
				 UIDs that the stream has.  If the
				 mailbox does not have matching UIDs
				 (e.g. the UIDs were lost or not
				 recorded) then the UID validity value
				 will be different
unsigned long uid_last;		highest currently assigned UID in the
				 current mailbox; a new UID will be
				 assigned with ++stream->uid_last
char *user_flags[NUSERFLAGS];	pointers to user flag names in bit
				 order from stream->perm_user_flags or
				 elt->user_flags

     The following MAILSTREAM values are only used internally:

DRIVER *dtb;			dispatch table for this driver
void *local;			pointer to driver local data
unsigned int lock : 1;		stream lock flag (an operation is in
				 progress; used as a bug trap to
				 detect recursion back to c-client
				 from callback routines).
unsigned int debug : 1;		debugging information should be logged
				 via mm_dlog().
unsigned int silent : 1;	don't do main program callbacks on
				 this stream (used when a stream is
				 opened internally)
unsigned int scache : 1;	short caching; don't cache information
				 in memory

     The following MAILSTREAM values are only used by the cache
manager routine (see the documentation about mailcache_t above):

unsigned long cachesize;	size of c-client message cache
union {
  void **c;			to get at the cache in general
  MESSAGECACHE **s;		message cache array
  LONGCACHE **l;		long cache array
} cache;