internal.txt

radius协议源码÷The Radius Stack will connect to a Radius Server. This stack implementation is built upo

DRIVER *mail_valid (MAILSTREAM *stream,char *mailbox,char *purpose);
	stream	if non-NIL, stream to use for validation
	mailbox	mailbox name to validate
	purpose	filled in as xxx in "Can't xxx" in error messages

     This function validates the given mailbox name.  It successful, it
returns the driver that can open that name if successful, otherwise it
returns NIL.  If stream is non-NIL, the mailbox name must be valid for
the type of mailbox associated with that stream (e.g. an NNTP name can
not be used with an IMAP stream).  If purpose is non-NIL, an error
message is passed via mm_log() when an error occurs.


DRIVER *mail_valid_net (char *name,DRIVER *drv,char *host,char *mailbox);
	name	mailbox name to validate
	drv	driver name to validate against
	host	buffer to return host name if non-NIL
	mailbox	buffer to return remote mailbox name if non-NIL

     This function is an alternative to mail_valid_net_parse().  It
validates the given mailbox name as a network name and makes sure that
its service name is the same as the driver in drv.  If successful, it
returns drv, and copies the host and mailbox strings as needed.
Otherwise it returns NIL.


long mail_valid_net_parse (char *name,NETMBX *mb);
	name	mailbox name to parse
	mb	pointer to NETMBX structure to return

     This function parses a network mailbox name.  If the name is a
network mailbox name, it returns non-NIL, with the NETMBX structure
loaded with the results form the parse.

		       Mailbox Access Functions

void mail_list (MAILSTREAM *stream,char *ref,char *pat);
void mail_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents);
	stream	if non-NIL, stream to use
	ref	mailbox reference string
	pat	mailbox pattern string
	contents contents to search

     This function returns a list of mailboxes via the mm_list()
callback.  The reference is applied to the pattern in an implementation
dependent fashion, and the resulting string is used to search for
matching mailbox names.  "*" is a wildcard which matches zero or more
characters; "%" is a variant which does not descend a hierarchy level.
Read the IMAP specification for more information.

     mail_scan() is a variant which takes a string to search for in the
text of the mailbox.  The string is a free-text string, without regard
for message boundaries, and thus the choice of strings must be made
with care.


void mail_lsub (MAILSTREAM *stream,char *ref,char *pat);
	stream	if non-NIL, stream to use
	ref	mailbox reference string
	pat	mailbox pattern string

     This function returns a list of subscribed mailboxes via the
mm_lsub() callback.  The reference is applied to the pattern in an
implementation dependent fashion, and the resulting string is used to
search for matching mailbox names in the subscription list.  "*" is a
wildcard which matches zero or more characters; "%" is a variant which
does not descend a hierarchy level.  Read the IMAP specification for
more information.


long mail_subscribe (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function adds the given name to the subscription list.  It
returns T if successful, NIL if unsuccessful.  If unsuccessful, an
error message is returned via the mm_log() callback.


long mail_unsubscribe (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function removes the given name from the subscription list.
It returns T if successful, NIL if unsuccessful.  If unsuccessful, an
error message is returned via the mm_log() callback.


long mail_create (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function creates a mailbox with the given name.  It returns T
if successful, NIL if unsuccessful.  If unsuccessful, an error message
is returned via the mm_log() callback.

     It is an error to create INBOX or a mailbox name which already
exists.


long mail_delete (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function deletes the named mailbox.  It returns T if
successful, NIL if unsuccessful.  If unsuccessful, an error message is
returned via the mm_log() callback.

     It is an error to delete INBOX or a mailbox name which does not
already exist.


long mail_rename (MAILSTREAM *stream,char *old,char *newname);
	stream	if non-NIL, stream to use
	old	existing mailbox name
	newname	new (not yet existing) mailbox name

     This function renames the old mailbox to the new mailbox name.
It returns T if successful, NIL if unsuccessful.  If unsuccessful, an
error message is returned via the mm_log() callback.

     It is an error to reanme a mailbox that does not exist, or rename
a mailbox to a name that already exists.  It is permitted to rename
INBOX; a new empty INBOX is created in its place.


long mail_status (MAILSTREAM *stream,char *mbx,long flags);
	stream	if non-NIL, stream to use
	mbx	mailbox name
	flags	option flags

     This function returns the status of the given mailbox name via the
mm_status() callback.  It returns T if successful, NIL if unsuccessful.
If unsuccessful, an error message is returned via the mm_log()
callback.

     The options are a bit mask with one or more of the following,
indicating the data which should be returned.
	SA_MESSAGES	number of messages in the mailbox
	SA_RECENT	number of recent messages in the mailbox
	SA_UNSEEN	number of unseen messages in the mailbox
	SA_UIDNEXT	next UID value to be assigned
	SA_UIDVALIDITY	UID validity value

     Note that, depending upon implementation, some of these values may
be more costly to get than others.  For example, calculating the
number of unseen messages may require opening the mailbox and scanning
all of the message flags.  A mail_status() call should thus be used
with option flags specifying only the data that is actually needed.


MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options);
	oldstream if non-NIL, stream to recycle
	name	mailbox name to open
	options	option flags.

     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; this is useful when you want to open
another mailbox to the same IMAP or NNTP server without having to open
a new connection.  Doing this will close the previously open 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)
	OP_PROTOTYPE	Return the "prototype stream" for the driver
			 associated with this mailbox instead of
			 opening the stream
	OP_HALFOPEN	For IMAP and NNTP names, open a connection
			 to the server but don't open a mailbox.
	OP_EXPUNGE	Silently expunge the oldstream before recycling

 NIL is returned if this function fails for any reason.


MAILSTREAM *mail_close (MAILSTREAM *stream);
MAILSTREAM *mail_close_full (MAILSTREAM *stream,long options);
	stream	stream to close
	options	option flags
     This function closes the MAIL stream and frees all resources
associated with it that it may have created (subject to any handles
existing).

     The options for mail_close_full() are a bit mask with one or more
of the following:
	CL_EXPUNGE	Silently expunge before closing

     This function always returns NIL, so it can be used as:
	stream = mail_close (stream);

			   Handle Functions

     Handles are used when an 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.


MAILHANDLE *mail_makehandle (MAILSTREAM *stream);
	stream	stream to make handle to

     This function creates and returns a handle to the stream.


void mail_free_handle (MAILHANDLE **handle);
	handle	pointer to handle to release

     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);
	handle	handle to look up

     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).

		    Message Data Fetching Functions

[Note!!  There is an important difference between a "sequence" and a
 "msgno".  A sequence is a string representing one or more messages in
 IMAP4-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_fetchfast (MAILSTREAM *stream,char *sequence);
void mail_fetchfast_full (MAILSTREAM *stream,char *sequence,long flags);
	stream	stream to fetch on
	sequence IMAP-format set of message sequence numbers
	flags	option flags

     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.

     The options for mail_fetchfast_full() are a bit mask with one or
more of the following:
	FT_UID		The sequence argument contains UIDs instead of
			 sequence numbers


void mail_fetchflags (MAILSTREAM *stream,char *sequence);
void mail_fetchflags_full (MAILSTREAM *stream,char *sequence,long flags);

     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.

 The options for mail_fetchflags_full() are a bit mask with one or more
of the following:
	FT_UID		The sequence argument contains UIDs instead of
			 sequence numbers


ENVELOPE *mail_fetchenvelope (MAILSTREAM *stream,unsigned long msgno);
ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,unsigned long msgno,
			       BODY **body);
ENVELOPE *mail_fetchstructure_full (MAILSTREAM *stream,unsigned long msgno,
				    BODY **body,long flags);
	stream	stream to fetch on
	msgno	message sequence number
	body	pointer to where to return BODY structure if non-NIL
	flags	option flags
     This function causes a fetch of all the structured 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.

     The options for mail_fetchstructure_full() are a bit mask with one
or more of the following:
	FT_UID		The msgno argument is a UID 

     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,unsigned long msgno);
char *mail_fetchheader_full (MAILSTREAM *stream,unsigned long msgno,
			     STRINGLIST *lines,unsigned long *len,long flags);
	stream	stream to fetch on
	msgno	message sequence number
	lines	list of header lines to fetch
	len	returned length in octets
	flags	option flags

     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.

     If the lines argument is non-NIL, it contains a list of header
field names to use in subsetting the header text.  Only those lines
which have that header field name are returned, unless FT_NOT is set in
which case only those lines which do not have that header field name
are returned.

     If the len argument is non-NIL, it holds a pointer in which the
length of the string in octets is returned.  This is useful in cases
where there may be an embedded null in the 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.

     The options for mail_fetchheader_full() are a bit mask with one or
more of the following:
	FT_UID		The msgno argument is a UID 
	FT_NOT		The returned header lines are those that are
			 not in the lines argument
	FT_INTERNAL	The return string is in "internal" format,
			 without any attempt to canonicalize to CRLF
			  newlines
	FT_PREFETCHTEXT	The RFC822.TEXT should be pre-fetched at the
			 same time.  This avoids an extra RTT on an
			 IMAP connection if a full message text is
			 desired (e.g. in a "save to local file"
			 operation)