Message store functions

C client support functions

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);
   
   char mail_string_next(STRING *s);
   

   void mail_string_setpos(STRING *s, unsigned long i);

mail_string is a basic string driver for a char* string.

mail_link
```
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 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.
auth_link
```
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 do not need to call this routine explicitly.
mail_parameters
```
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 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* (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.
- 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 in ``NNTP functions'' 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/IP 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: Do not change this without serious consideration. If other processes cannot 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(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.
- 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 (for example, /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 recursion that LIST will go on a ``*'' wildcard. Defaults to 20.
- GET_ANONYMOUSHOME/SET_ANONYMOUSHOME
  The anonymous use home directory name.
See also ``mail_parameters functions''.
readfn_t
```
typedef long(*readfn_t)(void *stream, unsigned long size, char *buffer);
```
stream
A suitable designator.

size
The number of octets to read.

buffer
A buffer of at least size octets for reading.

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.
mailgets_t
```
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 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.
mailcache_t
```
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, 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:

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 elt (or lelt) for msgno.

CH_EXPUNGE
Free the elt (or lelt) for msgno, and reclaim its position. All subsequent elts are renumbered with their elt->msgno decremented by 1. (Hence msgno+1 becomes msgno, and so on.) This supports message expunging from the cache.
tcptimeout_t
```
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 (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.
mail_valid
```
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, 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.
mail_valid_net
```
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.
mail_valid_net_parse
```
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 name is a network mailbox name, it returns non-NIL, with the NETMBX structure loaded with the results from the parse.
mail_list and mail_scan
```
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.

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.
mail_lsub
```
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 that matches zero or more characters; ``%'' is a variant that does not descend a hierarchy level. Read the IMAP specification for more information.
mail_subscribe
```
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.
mail_unsubscribe
```
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.
mail_create
```
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.
mail_delete
```
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.
mail_rename
```
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 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.
mail_status
```
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.
mail_open
```
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
Do not use or update a .newsrc file for news.

OP_SHORTCACHE
Do not cache envelopes or body structures.

OP_SILENT
Do not 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 do not open a mailbox.

OP_EXPUNGE
Silently expunge the oldstream before recycling.

NIL is returned if this function fails for any reason.
mail_close
```
MAILSTREAM *mail_close(MAILSTREAM *stream);

MAILSTREAM *mail_close_full(MAILSTREAM *stream, long options);
```
stream
Stream to close.

options
Option flags.

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:

CL_EXPUNGE
Silently expunge before closing.

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