internal.txt

SIP 1.5.0源代码

	data	pointer to driver-dependent data, from which the
		 driver can determine string data
	size	size of the string
 This method initializes the string stucture.  It can use the data,
data1, and chunksize values as it likes.  The remaining values must be
set up as follows:
	size		static, copied from the size argument
	chunk		pointer to a buffer loaded with initial data
	chunksize	size of the buffer
	offset		0
	curpos		copied from chunk
	cursize		copied from chunksize
	dtb		STRINGDRIVER identity pointer


char (*next) (STRING *s);
	s	pointer to the string structure
 This method returns the character at the current string character
pointer, and increments the string character pointer.  This method
is likely to call the setpos method if the desired character is not in
the current chunk.


void (*setpos) (STRING *s,unsigned long i);
	s	pointer to the string structure
	i	new string pointer value
 This method sets the string character pointer to the given value.  If
the pointer is not in the current chunk, then a new chunk is loaded
and the associated values (chunk, offset, curpos, cursize) are
adjusted accordingly.

		      c-client Support Functions


void mail_string_init (STRING *s,void *data,unsigned long size);
char mail_string_next (STRING *s);
void mail_string_setpos (STRING *s,unsigned long i);

     These three functions are the init, next, and setpos string
structure access methods for the build-in mail_string string driver.
mail_string is a basic string driver for a char* string.  See the
documentation below on "String Structions" for more information.


void mail_link (DRIVER *driver);
	driver	pointer to the driver to be added

     This function adds the specified driver to the list of mailbox
drivers.  Initially there are no drivers lunk, so all programs which
intend to use c-client need to have at least one call to this function.

     A function which uses IMAP4 would have a statement such as:
	mail_link (&imapdriver);	/* link in IMAP driver */
early in the program's initialization.  Normally, this is done by the
statement
	#include "linkage.c"
which will include the "system standard driver linkage" defined when
c-client was built.  By using linkage.c instead of explicit mail_link()
calls, you are guaranteed that you will have a consistant linkage among
all software built on this system.


void auth_link (AUTHENTICATOR *auth);
	auth	pointer to the authenticator to be added

     This function adds the specified authenticator to the list of
authenticators.  Initially there are no authenticators lunk.  Normally,
this is done by linkage.c so you don't need to call this routine
explicitly.


void *mail_parameters (MAILSTREAM *stream,long function,void *value);
	stream	stream to poll or NIL
	function function code
	value	new value for function codes that change a parameter

     This function fetches or changes the settings of various c-client
operational parameters depending upon the function.  If the stream is
specified, only the action for the underlying driver for that stream is
taken; however, the scope of the operational parameters is global so
there is generally no reason for the stream argument ever to be
non-NIL.

     The function codes ENABLE_DRIVER and DISABLE_DRIVER take a driver
pointer as a value.  These functions enable and disable mailbox
processing by that driver.  By default, all drivers are enabled.

     The remaining the function codes are in a pair named GET_xxx to
fetch an operational parameter and SET_xxx to set the parameter:

 GET_DRIVERS / SET_DRIVERS
	 The list of currently lunk drivers.

 GET_GETS / SET_GETS
	 If non-NIL, points to a function for reading message text.
	Defaults to NIL.
	 This function is called with three arguments; a function
	pointer to a "reading function", a stream for the reading
	function, and a size in octets.  The reading function is
	in turn called with the stream, a size in octets, and a
	pointer to a readin buffer.
	 This function returns with a char* string, which will be
	returned by the mail_fetchheader(), mail_fetchtext(), or
	mail_fetchbody() function which triggered the message text
	reading.
	 The purpose is to permit reading of large strings, without
	requiring an in-memory buffer for the entire string.  The idea
	is that this function can store the data in some form other
	than a char* (e.g. a temporary file) and the main program will
	recognize that it should get the text from there instead of
	from the results from mail_fetch....().
	 This is only supported on DOS and Win16; on other platforms it
	is inconsistent whether or not it works.

 GET_CACHE / SET_CACHE
	 Points to the c-client cache manager function.  Defaults to
	mm_cache().

 GET_SMTPVERBOSE / SET_SMTPVERBOSE
	 If non-NIL, points to a function that accepts a char* string.
	This function is called any time the SMTP routines receive a
	response code less than 100.  The argument is the text of the
	response code

 GET_RFC822OUTPUT / SET_RFC822OUTPUT
	 If non-NIL, points to an alternate rfc822_output() function.
	rfc822_output() will call this function and return instead of
	doing its normal action.  See the description of
	rfc822_output() for more information.	

 GET_USERNAME / SET_USERNAME
	 The logged-in user name.

 GET_HOMEDIR / SET_HOMEDIR
	 The home directory path name.

 GET_LOCALHOST / SET_LOCALHOST
	 The local host name.

 GET_SYSINBOX / SET_SYSINBOX
	 The "system INBOX" (where mail is delivered) path name.

 GET_OPENTIMEOUT / SET_OPENTIMEOUT
	 TCP/IP open timeout in seconds.  Defaults to 0 (system
	default timeout, usually 75 seconds on Unix).
	
 GET_READTIMEOUT / SET_READTIMEOUT
	 TCP/IP read timeout in seconds.  Defaults to 0 (no timeout).

 GET_WRITETIMEOUT / SET_WRITETIMEOUT
	 TCP/IP write timeout in seconds.  Defaults to 0 (no timeout).

 GET_CLOSETIMEOUT / SET_CLOSETIMEOUT
	 TCP/IP close timeout in seconds.  Defaults to 0 (no timeout).

 GET_TIMEOUT / SET_TIMEOUT
	 If non-NIL, points to the function called when a TCP/IP
	timeout occurs.  This function is called with the number of
	seconds since the start of the TCP operation.  If it returns
	non-zero, the TCP/IP operation is continued; if it returns
	non-zero, the TCP/IP connection is aborted.

 GET_RSHTIMEOUT / SET_RSHTIMEOUT
	 rsh connection timeout in seconds.  Defaults to 15 seconds.

 GET_MAXLOGINTRIALS / SET_MAXLOGINTRIALS
	 The maximum number of login attempts permitted in an IMAP or
	POP connection.  Defaults to 3.

 GET_LOOKAHEAD / SET_LOOKAHEAD
	 The number of subsequent envelopes prefetched in IMAP when an
	envelope is fetched.  Defaults to 20.

 GET_IMAPPORT / SET_IMAPPORT
	 The IMAP port number.  Defaults to 143.

 GET_PREFETCH / SET_PREFETCH
	 The number of envelopes prefetched in IMAP from the results
	of a SEARCH.  Defaults to 20.

 GET_CLOSEONERROR / SET_CLOSEONERROR
	 If non-NIL, close an opening IMAP connection if the SELECT
	command fails instead of returning a half-open stream.
	Defaults to NIL.

 GET_POP3PORT / SET_POP3PORT
	 The POP3 port number.  Defaults to 110.

 GET_UIDLOOKAHEAD / SET_UIDLOOKAHEAD
	 The number of UIDs premapped when a message number is
	translated to a UID.  Defaults to 1000.

 GET_MBXPROTECTION / SET_MBXPROTECTION
	 Default file protection for newly created mailboxes.
	Defaults to 0600.

 GET_DIRPROTECTION / SET_DIRPROTECTION
	 Default file protection for newly created directories.
	Defaults to 0700.

 GET_LOCKPROTECTION / SET_LOCKPROTECTION
	 Default file protection for locks.  Defaults to 0666.
	WARNING: don't blithely change this.  If other processes
	can't get access to a lock then they will have trouble in
	locking properly.

 GET_FROMWIDGET / SET_FROMWIDGET
	 If non-NIL, APPEND in the Unix mbox format will insert a
	">" character in front of all lines which begin with the
	string "From ".  If NIL, it will only do so if the entire
	line looks like a message delimiter (that is, the date is
	also in correct format).  Defaults to T.

 GET_NEWSACTIVE / SET_NEWSACTIVE
	 Netnews active file path name.

 GET_NEWSSPOOL / SET_NEWSSPOOL
	 Netnews spool directory path name.

 GET_NEWSRC / SET_NEWSRC
	 Netnews newsgroup reading status file (.newsrc) path name.

 GET_EXTENSION / SET_EXTENSION
	 If non-NIL, points to a string holding the extension for all
	mailbox files.  This is only supported on DOS and Win16.

 GET_DISABLEFCNTLLOCK / SET_DISABLEFCNTLLOCK
	 If non-NIL, disables fcntl() locking on SVR4.  This is done
	if fcntl() tends to hang for no good reason.  Now that the
	fcntl() code checks for NFS files and no-ops the locking,
	this problem usually doesn't happen much any more.  Defaults
	to NIL.

 GET_LOCKEACCESERROR / SET_LOCKEACCESERROR
	 If non-NIL, give a warning if an attempt to create a .lock
	file gets an EACCES ("Permission denied") error.  This usually
	means that somebody protected the system inbox directory (e.g.
	/var/mail) instead of making it public-write with the sticky
	bit.  Defaults to non-NIL, since this is usually bad news.

 GET_LISTMAXLEVEL / SET_LISTMAXLEVEL
	 The maximum depth of recusion that LIST will go on a *
	wildcard.  Defaults to 20.

 GET_ANONYMOUSHOME / SET_ANONYMOUSHOME
	 The anonymous use home directory name.


typedef long (*readfn_t) (void *stream,unsigned long size,char *buffer);
	stream	a designator suitable
	size	a number of octets to read
	buffer	a buffer of at least size octets for readin

     This function reads the given number of octets into the buffer,
using the given stream.  What sort of object the stream is depends upon
the function and its caller, so you must make sure that the readfn is
suitable for the caller's purpose.  Common uses include support of the
mailgets function (see below) and of reading from local files on systems
with limited address apce.


typedef char *(*mailgets_t) (readfn_t f,void *stream,unsigned long size);
	f	the readfn to use
	stream	stream argument for the readfn
	size	total number of octets to read

     This is the argument to the SET_GETS mail_parameter() call.  This
function must read size octets from the stream, using the readfn f.  It
may call f multiple times to accomplish this; this will read the data in
a serial fashion.  So, for example, if size is a megabyte and there is
only 4K of available buffer space, it can call f 256 times to satisfy
the request.  There is no way to back up in the reading, so any
processing or saving of the data must be done when it is read.

     The function mm_gets() in mail.c is a sample mailgets function; it
reads the first MAXMESSAGESIZE of data into memory and discards the
rest.


typedef void *(*mailcache_t) (MAILSTREAM *stream,unsigned long msgno,long op);
	stream	stream to cache manage
	msgno	message to cache manage in the stream
	op	cache management operation

     This function manages the c-client cache.  Normally, a program will
use the default c-client cache manager routine mm_cache().  However, a
main program may want to supply its own cache manager, e.g. it may want
to store the data on a disk file instead of in memory on DOS and Win16
where memory is tight.

     If you write your own cache manager, you need to examine the
default mm_cache() manager closely, as well as paying close attention to
what goes into an elt (a MESSAGECACHE element).  It is highly likely
that if you roll elts out to disk, you will want to set stream->scache
and *NOT* use long elts (because long elts have ENVELOPE and BODY
pointers that you would have to know how to write to disk and read back).

     The cache management functions are one of the following:

 CH_INIT	 Initialize the entire cache for the stream.  This is
		called only when creating a new stream or when freeing
		it.  The msgno argument is ignored.

 CH_SIZE	 Make sure that the cache is at least large enough to
		support msgno.  This is a request to grow the cache if
		necessary, not shrink it.

 CH_MAKELELT	 Return a long elt for msgno, creating it if necessary.
		This is the underlying support function for mail_lelt().

 CH_LELT	 Return the long elt for msgno, or NIL if it does not
		already exist.

 CH_MAKEELT	 Return an elt for msgno, creating it if necessary.
		This is the underlying support function for mail_elt().

 CH_ELT		 Return the elt for msgno, or NIL if it does not already
		exist.

 CH_FREE	 Free the [l]elt for msgno.

 CH_EXPUNGE	 Free the [l]elt for msgno, and reclaim its position.
		All subsequent elts are renumbered with their elt->msgno
		decremented by 1.  [Hence msgno+1 becomes msgno, etc.]
		This supports message expunging from the cache.


typedef long (*tcptimeout_t) (long time);
	time	total time spent since TCP operation started

     This function is called when a TCP operation times out.  It is set
by the SET_TIMEOUT mail_parameter().  The function can return non-zero
to continue the TCP operation (e.g. after outputting a "do you still
want to wait" prompt) or zero if it wants the TCP operation to abort and
close.  If the TCP operation aborts, it will likely cause the upper
level IMAP, SMTP, etc. stream to abort and close as well.