internal.txt

SIP 1.5.0源代码

     The following MAILSTREAM values are for the convenience of
drivers that use short caching and want to be able to garbage collect
any values that they returned:

unsigned long msgno;		message number of `current' message
ENVELOPE *env;			pointer to `current' message envelope
BODY *body;			pointer to `current' message body
char *text;			pointer to `current' text


     The MESSAGECACHE structure (commonly called an "elt" as a
nickname for "cache ELemenT") contains information about messages.
Applications may use the following:

unsigned long msgno;		message number.  If the elt is locked
				 (by elt->lockcount++), then the elt
				 pointer can be stored (e.g. with the
				 data for a window which draws this
				 message) and elt->msgno will change
				 automatically whenever expunges are
				 done so the window will always view
				 the correct message.  If elt->msgno
				 becomes 0, then the message has been
				 expunged, but the elt won't be freed
				 until the elt lock count is
				 decremented (by mail_free_elt()).
unsigned long uid;		message unique ID
unsigned int hours: 5;		internal date hours (0-23)
unsigned int minutes: 6;	internal date minutes (0-59)
unsigned int seconds: 6;	internal date seconds (0-59)
unsigned int zoccident : 1;	non-zero if internal date time zone is
				 west of UTC
unsigned int zhours : 4;	internal date time zone hours from UTC
				 (0-12)
unsigned int zminutes: 6;	internal date time zone minutes (0-59)
unsigned int seen : 1;		message Seen flag
unsigned int deleted : 1;	message Deleted flag
unsigned int flagged : 1; 	message Flagged flag
unsigned int answered : 1;	message Answered glag
unsigned int draft : 1;		message Draft flag
unsigned int valid : 1;		flags are valid in this elt; an elt
				 that was newly created but never
				 loaded with flags won't have this set.
unsigned int recent : 1;	message recent flag
unsigned int searched : 1;	message matches search criteria in
				 most recent mail_search_full() call
unsigned int spare : 1;		reserved for application use
unsigned int spare2 : 1;	reserved for application use
unsigned int spare3 : 1;	reserved for application use
unsigned int lockcount : 8;	non-zero if multiple references to
				 this elt.  Refer to the msgno member
				 for more information.
unsigned int day : 5;		internal date day of month (1-31)
unsigned int month : 4;		internal date month of year (1-12)
unsigned int year : 7;		internal date year since BASEYEAR
				 (currently 1970; was 1969 in older
				 versions so use BASEYEAR instead of
				 having the base year wired in)
unsigned long user_flags;	message user flags; this is a bit mask
				 which matches the entries in
				 stream->user_flags[]
unsigned long rfc822_size;	size of message in octets

     The following MESSAGECACHE values are only used internally by
drivers:

unsigned int sequence : 1;	message is in sequence from either
				 mail_sequence() or mail_uid_sequence()
unsigned long data1;		first data item
unsigned long data2;		second data item
unsigned long data3;		third data item
unsigned long data4;		fourth data item


     The ADDRESS structure is a parsed form of a linked list of RFC 822
addresses.  It contains the following information:

char *personal;			personal name phrase
char *adl;			at-domain-list (also called "source
				 route")
char *mailbox;			mailbox name
char *host;			domain name of mailbox's host
char *error;			error in address from smtp_mail(); if
				 an error is returned from smtp_mail()
				 for one of the recipient addresses
				 the SMTP server's error text for that
				 recipient can be found here.  If it
				 is null then there was no error (or
				 an error was found with a prior
				 recipient
ADDRESS *next;			pointer to next address in list


     The ENVELOPE structure is a parsed form of the RFC 822 header.
Its member names correspond to the RFC 822 field names.  It contains
the following information:

char *remail;			remail header if any
ADDRESS *return_path;		error return address
char *date;			message composition date string
ADDRESS *from;			from address list
ADDRESS *sender;		sender address list
ADDRESS *reply_to;		reply address list
char *subject;			message subject string
ADDRESS *to;			primary recipient list
ADDRESS *cc;			secondary recipient list
ADDRESS *bcc;			blind secondary recipient list
char *in_reply_to;		replied message ID
char *message_id;		message ID
char *newsgroups;		USENET newsgroups
char *followup_to;		USENET reply newsgroups
char *references;		USENET references


     The BODY structure is a parsed form of a linked list of the MIME
structure of a message.  It contains the following information.

unsigned short type;		body primary type code.  This is an
				 index into the body_types vector of
				 body type names.  The following body
				 types are pre-defined:
	TYPETEXT		unformatted text
	TYPEMULTIPART		multiple part
	TYPEMESSAGE		encapsulated message
	TYPEAPPLICATION		application data
	TYPEAUDIO		audio
	TYPEIMAGE		static image (GIF, JPEG, etc.)
	TYPEVIDEO		video
	TYPEOTHER		unknown
				Additional types up to TYPEMAX are
				 dynamically defined if they are
				 encountered by c-client.
unsigned short encoding;	body transfer encoding.  This is an
				 index into the body_encodings vector
				 of body encoding names.  The
				 following body encodings are
				 pre-defined:
	ENC7BIT			7 bit SMTP semantic data
	ENC8BIT			8 bit SMTP semantic data
	ENCBINARY		8 bit binary data
	ENCBASE64		base-64 encoded data
	ENCQUOTEDPRINTABLE	human-readable 8-as-7 bit data
	ENCOTHER		unknown
				Additional encodings up to ENCMAX are
				 dynamically defined if they are
				 encountered by c-client.
char *subtype;			body subtype string
PARAMETER *parameter;		parameter list
char *id;			body content identifier
char *description;		body content description
unsigned char *contents.text;	when composing a message that is NOT
				 of TYPEMULTIPART, non-binary text of
				 the content is stored here.  Note that
				 this happens even when the text is
				 of TYPEMESSAGE.  Text of encoding
				 ENC8BIT may be converted to
				 ENCQUOTEDPRINTABLE when it is sent.
				 This should not be referenced for any
				 other reason; in particular, this is
				 NOT the way for an application to
				 access content data (use
				 mail_fetchbody_full() instead).
BINARY *contents.binary;	when composing a message that is NOT
				 of TYPEMULTIPART, binary content (of
				 encoding ENCBINARY) is stored here.
				 It will be converted to ENCBASE64 when
				 it is sent.
				 This should not be referenced for any
				 other reason; in particular, this is
				 NOT the way for an application to
				 access content data (use
				 mail_fetchbody_full() instead).
PART *contents.part;		for body parts of TYPEMULTIPART, this
				 contains the list of body parts in
				 this multipart
MESSAGE contents.msg;		for body parts of TYPEMESSAGE with
				 subtype "RFC822", this contains the
				 encapsulated message
unsigned long size.lines;	size in lines
unsigned long size.bytes;	size in octets.  This MUST be set when
				composing a message if the encoding is
				ENC8BIT or ENCBINARY.
char *md5;			body content MD5 checksum

     The following BODY information is used only by c-client
internally.  The use of this data is driver-specific and it can not be
relied-upon by applications.

unsigned char *contents.text;	drivers can store a pointer to the
				 body contents as text here.		
unsigned long size.ibytes;	internal size of the body content (prior
				 to newline conversion, etc.) in octets


     The MESSAGE structure is a parsed form of a MESSAGE/RFC822 MIME
body part.  It contains the following information:

ENVELOPE *env;			encapsulated message RFC 822 header
BODY *body;			encapsulated message MIME structure

     The following MESSAGE information is used only by c-client
internally.  The use of this data is driver-specific and it can not be
relied-upon by applications.

char *hdr;			encapsulated message header
unsigned long hdrsize;		message header size
char *text;			message in RFC 822 form
unsigned long offset;		offset of text from header


     The PARAMETER structure is a parsed form of a linked list of
attribute/value pairs.  It contains the following information:

char *attribute;		attribute name
char *value;			value
PARAMETER *next;		next parameter in list


     The PART structure is a parsed form of a linked list of MIME body
parts.  It contains the following information:

BODY body;			body information for this part
PART *next;			next body part

     The following PART information is used only by c-client
internally.  The use of this data is driver-specific and it can not be
relied-upon by applications.

unsigned long offset;		offset from body origin


    The NETMBX structure is a parsed form of a network mailbox name:

char host[NETMAXHOST];		remote host name
char user[NETMAXUSER];		remote user name if specified
char mailbox[NETMAXMBX];	remote mailbox name
char service[NETMAXSRV];	remote service name (IMAP4, NNTP, etc.)
unsigned long port;		TCP/IP port number if specified
unsigned int anoflag : 1;	anonymous access requested
unsigned int dbgflag : 1;	protocol debugging telemetry, via
				 mm_dlog(), requested


     The STRINGLIST structure is a list of strings (which may have
embedded NULs) and their lengths:

char *text;			string text
unsigned long size;		string length
STRINGLIST *next;		next string in list

			  String Structures

     A string structure is analogous to a char*, and is used in some
functions as an input argument.  It represents a string of data in a
way that does not necessarily require the entire string to be in
memory at once.  This is essential for small machines with
highly-restricted memory limits (e.g. DOS).

		       String Structure Access

     To use a string structure, the caller needs to know a string
driver and needs to know the driver-dependent data used by that string
structure.  A simple string driver is mail_string, a string driver
that takes an in-memory char* string as the driver-dependent data.
The DOS port uses string drivers that take a struct holding a file
descriptor and a file offset.  Often the user of a string driver is
the same module that defined it, so usually the programmer knows about
its conventions.

     The following calls are used to access a string structure:

void INIT (STRING *s,STRINGDRIVER *d,void *data,unsigned long size);
	s	pointer to the string structure to be initialized
	d	pointer to the string driver
	data	pointer to driver-dependent data, from which the
		 driver can determine string data
	size	size of the string
 This call initializes the string stucture.


unsigned long SIZE (STRING *s);
	s	pointer to the string structure
 This call returns the number of characters remaining in the string
after the current string character pointer.


char CHR (STRING *s);
	s	pointer to the string structure
 This call returns the character at the current string character
pointer.


char SNX (STRING *s);
	s	pointer to the string structure
 This call returns the character at the current string character
pointer, and increments the string character pointer.


unsigned long GETPOS (STRING *s);
	s	pointer to the string structure
	i	new string pointer value
 This returns the value of the current string character pointer.


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.


		      String Structure Internals

     A string structure holds the following data:

void *data;		used by the string driver as it likes
unsigned long data1;	used by the string driver as it likes
unsigned long size;	static, holds the total length of the string
			 from the INIT call
char *chunk;		current chunk of in-memory data; this is used
			 for buffering to avoid unnecessary calls to
			 the string driver's next method.
unsigned long chunksize; size of an in-memory data chunk
unsigned long offset;	position of first character of the chunk in
			 the overall string
char *curpos;		current position; this is what CHR() will
			 access
unsigned long cursize;	number of characters remaining in the current
			 string
STRINGDRIVER *dtb;	the string driver for this string structure


     A string structure is manipulated by a string driver, which has
the following access methods:

void (*init) (STRING *s,void *data,unsigned long size);
	s	pointer to the string structure to be initialized