|
|
The following functions are the init, next, and setpos string structure access methods for the built-in mail_string string driver.
void mail_string_init(STRING *s, void *data, unsigned long size);mail_string is a basic string driver for achar mail_string_next(STRING *s);
void mail_string_setpos(STRING *s, unsigned long i);
char*
string.
void mail_link(DRIVER *driver);
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 the C client interface need to have at least one call to this function.
A function that uses IMAP4 would have a statement such as the following early in the program's initialization:
mail_link(&imapdriver); /* link in IMAP driver */Normally, this is done by the following statement:
#include "linkage.c"This will include the system standard driver linkage defined when the C client was built. By using linkage.c instead of explicit mail_link calls, you are guaranteed that you will have a consistent linkage among all software built on this system.
void auth_link(AUTHENTICATOR *auth);
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 do not need to call this routine explicitly.
void *mail_parameters(MAILSTREAM *stream, long function, void *value);
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 function codes are in a pair named GET_xxx to fetch an operational parameter and SET_xxx to set the parameter:
The list of currently lunk drivers.
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*
(for example, 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.
Points to the C client cache manager function. Defaults to mm_cache.
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.
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 in ``NNTP functions'' for more information.
The logged-in user name.
The home directory path name.
The local host name.
The system INBOX (where mail is delivered) path name.
TCP/IP open timeout in seconds. Defaults to 0 (system default timeout, usually 75 seconds on UNIX).
TCP/IP read timeout in seconds. Defaults to 0 (no timeout).
TCP/IP write timeout in seconds. Defaults to 0 (no timeout).
TCP/IP close timeout in seconds. Defaults to 0 (no 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/IP operation. If it returns non-zero, the TCP/IP operation is continued; if it returns non-zero, the TCP/IP connection is aborted.
rsh connection timeout in seconds. Defaults to 15 seconds.
The maximum number of login attempts permitted in an IMAP or POP connection. Defaults to 3.
The number of subsequent envelopes prefetched in IMAP when an envelope is fetched. Defaults to 20.
The IMAP port number. Defaults to 143.
The number of envelopes prefetched in IMAP from the results of a SEARCH. Defaults to 20.
If non-NIL, close an opening IMAP connection if the SELECT command fails instead of returning a half-open stream. Defaults to NIL.
The POP3 port number. Defaults to 110.
The number of UIDs premapped when a message number is translated to a UID. Defaults to 1000.
Default file protection for newly created mailboxes. Defaults to 0600.
Default file protection for newly created directories. Defaults to 0700.
Default file protection for locks. Defaults to 0666.
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.
Netnews active file path name.
Netnews spool directory path name.
Netnews newsgroup reading status file (.newsrc) path name.
If non-NIL, points to a string holding the extension for all mailbox files. This is only supported on DOS and Win16.
If non-NIL, disables fcntl(2) 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 does not happen much any more. Defaults to NIL.
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 (for example, /var/mail) instead of making it public-write with the sticky bit. Defaults to non-NIL, since this is usually bad news.
The maximum depth of recursion that LIST will go on a ``*'' wildcard. Defaults to 20.
The anonymous use home directory name.
See also ``mail_parameters functions''.
typedef long(*readfn_t)(void *stream, unsigned long size, char *buffer);
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
readfn
is suitable for the caller's purpose. Common uses
include support of the mailgets function and of reading
from local files on systems with limited address apce.
typedef char *(*mailgets_t)(readfn_t f, void *stream, unsigned long size);
readfn
to use.
readfn
.
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
4KB 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);
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, for example, 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:
elt->msgno
decremented by 1. (Hence msgno+1 becomes msgno,
and so on.) This supports message expunging from the cache.
typedef long (*tcptimeout_t)(long time);
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
(for example, 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, and so on, stream
to abort and close as well.
DRIVER *mail_valid(MAILSTREAM *stream, char *mailbox, char *purpose);
Can't
xxx in error
messages.
This function validates the given mailbox name. It successful, it returns the driver that can open that name, otherwise it returns NIL. If stream is non-NIL, the mailbox name must be valid for the type of mailbox associated with that stream (for example, 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);
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);
This function parses a network mailbox name. If name is a network mailbox name, it returns non-NIL, with the NETMBX structure loaded with the results from the parse.
void mail_list(MAILSTREAM *stream, char *ref, char *pat);void mail_scan(MAILSTREAM *stream, char *ref, char *pat, char *contents);
These functions return 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 that 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);
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 that matches zero or more characters; ``%'' is a variant that does not descend a hierarchy level. Read the IMAP specification for more information.
long mail_subscribe(MAILSTREAM *stream, char *mailbox);
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);
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);
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);
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);
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 rename 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);
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.
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);
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:
NIL is returned if this function fails for any reason.
MAILSTREAM *mail_close(MAILSTREAM *stream);MAILSTREAM *mail_close_full(MAILSTREAM *stream, long options);
These functions close the MAIL stream and free 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:
This function always returns NIL, so it can be used as follows:
stream = mail_close(stream);