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 inconsistant 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. 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.