Edit File: internal.txt
/* ======================================================================== * Copyright 1988-2006 University of Washington * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * * ======================================================================== */ Documentation of c-client Functions and Interfaces REVISED: 19 August 1996 Credits The original version of this document was written by Mark Crispin at the University of Washington, and described the version of c-client that supported the IMAP2 (RFC 1176) and IMAP2bis (unpublished) protocols. This version is a substantial rewrite of that document, and was written by Mark Crispin with funding from Sun Microsystems, Incorporated. Sun's generous support of this work is gratefully acknowledged. Road Map This document is organized into the following sections. Except as noted, an implementor of an application that uses c-client needs to be familiar with all of these sections. Someone who plans to write a new mailbox driver for c-client (or otherwise modify it) needs to be familiar with all sections, no exception. History History of how c-client came about. Overview Read this before designing an application that uses c-client. c-client Structures Documentation of several important c-client structs which are used in, and returned by, c-client calls. String Structures Documentation of the concept of a "string structure", which provides random access to strings without requiring that the string be in memory. c-client Support Functions Documentation of support functions for c-client; these deal with c-client functionality. Only mail_parameters() is of interest to most application developers. Advanced application developers, particularly for limited memory systems, may also need to know about the readfn_t, mailgets_t, mailcache_t, and tcptimeout_t function pointer types, and possibly also the mail_valid_net_parse() function. Mailbox Access Functions Documentation of functions which deal with mailboxes; listing, subscribing, creating, deleting, renaming, status inquiries, opening, and closing mailboxes. Handle Functions Documentation of mail stream handles, which provide protection for an advanced application which may have multiple pointers to a single mail stream. If a stream has a handle on it, closing the stream does not release its memory, so pointers to it in the application remain valid. Freeing the last handle will free the entire stream. This is only of interest for advanced application developers. Message Data Fetching Functions Documentation on message data fetching in an open mailbox, including parsed representations of RFC-822 and MIME headers and message text. Also how to fetch message attributes (flags, internal date, sizes). Message Status Manipulation Functions Documentation on altering message flags in an open mailbox. Mailbox Searching Documentation on searching an open mailbox for messages which match certain criteria (e.g. "messages sent July 4 from Jones with text `Paris'"). Miscellaneous Mailbox and Message Functions Documentation on other operations that would be used by an application but that don't fit into any of the above categories. Date/Time Handling Functions Documentation on functions that deal with date/time strings. This is only of interest for advanced application developers and for implementors of new c-client drivers. Utility Functions Documentation on internal utility functions. This is primarily of interest for implementors of new c-client drivers, but advanced application developers may also use some of these functions. Data Structure Instantiation/Destruction functions Documentation on creating and destroy c-client structures. This is primarily of interest for implementors of new c-client drivers. However, application developers will need some of these functions to create and destroy structures which are used as arguments to various application functions. Authentication Functions Documentation on support for network protocol authentication functions. This is only of interest for implementors of new c-client drivers which deal with authentication mechanisms. Network Access Functions Documentation on creating and destroy c-client structures. This is primarily of interest for implementors of new c-client drivers which deal with a network. However, advanced application developers may need to use this information if they wish to insert their own layer into a network session. Subscription Management Functions Documentation on managing the local (client-based) subscription database file. This is primarily of interest to advanced application developers. Miscellaneous Utility Functions Documentation on various useful utility functions, such as "make a copy of this string." SMTP Functions Documentation on posting email messages via SMTP protocol. NNTP Functions Documentation on posting netnews messages via NNTP protocol. RFC 822 Support Functions Documentation on public RFC-822/MIME functions. This is primarily of interest for implementors of new c-client drivers and advanced application developers. Operating System-Dependent Public Interface Documentation on OS-dependent functions. With the exception of fs_get(), fs_give(), and fs_resize(), which should be called instead of malloc(), free(), and realloc(), these functions are primarily of interest for implementors of new c-client drivers. Main Program Callbacks Documentation of functions which the main program must provide as callbacks from c-client. Driver Interface Documentation of the driver dispatch vector and the functions which a driver must supply. This is primarily of interest for implementors of new c-client drivers. Driver Support Functions Documentation of support functions which are called by drivers. This is primarily of interest for implementors of new c-client drivers. History The c-client API was originally written by Mark Crispin at Stanford University as a set of routines to support IMAP and SMTP from a main program which would handle the user interface. In its original form, it was written as the low-level routines that were to be used as part of a Macintosh client. The first IMAP client, MM-D (for "MM on Xerox D machines" -- MM was a popular DEC-20 mail program) was written in Interlisp for Xerox Lisp machines. At that time, there was no name for the embryonic Mac client, but since it was the first one to be written in C instead of Lisp, it was given a development name of "C client". This name became "c-client" because that is the name of the subdirectory on UNIX where the source files were stored. To exercise the routines, a minimal main program which uses c-client, mtest, was written. mtest has subsequently been extended so that it runs on every platform that c-client is ported. The real Mac client, was eventually written by Frank Gilmurrary and Bill Yeager at Stanford using the autumn 1988 version of c-client and named "MacMS". In the winter of 1988-89, Mark Crispin, who had changed jobs to the University of Washington, developed MS as an MM-like text-based program for UNIX and MailManager as a GUI-based program for NeXT machines. The realization sunk in that this API needed its own name. As early as spring 1989, there were at least four programs (mtest, MS, MailManager, and MacMS) that used it. The name c-client thus became permanent. In its history, c-client has undergone two major redesigns, both by Mark Crispin who is now on the staff at the University of Washington. The first major redesign added the following: 1) ANSI C calling conventions throughout to assist in function argument type checking. 2) Vectoring mail access calls through "driver" methods; thus providing transparent access to multiple types of mail stores with the same call. 3) MIME support. The second major redesign was part of the IMAP4 project. Many c-client functions were extended with additional arguments and options. The driver interface was also made simpler, with more work done by driver-independent code. Overview The most important file for the author of an application using the c-client is mail.h. mail.h defines several important structures of data which are passed between the main program and the c-client. Although some functions (e.g. mail_fetchtext_body()) return the data fetched, for certain other data items (e.g. flags) you need to get the data as a structure reference. mail.h also defines a large number of useful constants and structures. When a function in mail.h exists to reference data, it MUST be used instead of referencing the structures directly. This is because in some cases the data is not actually fetched until a reference (via the function call) is made. For example, although the MESSAGECACHE element for a message can be obtained by indexing the proper cache element in the stream, there is no guarantee that the item in fact exists unless mail_fetchstructure_full() is called for that message. Less costly functions. also exist to create and load a MESSAGECACHE element. The main program will probably also need to include smtp.h, misc.h, and osdep.h, but this usage should be solely to receive function prototypes. Any other definitions in those files should be considered private to that module. Two important predefined symbols are NIL and T. NIL is any sort of "false"; T is any sort of "true". NIL is also used to null-specify certain optional arguments. * * * IMPORTANT * * * Any multi-threaded application should test stream->lock prior to calling any c-client stream functions. Any attempt to call a mail_xxx() function while one is already in progress on the same stream will cause the application to fail in unpredictable ways. Note that this check is insufficient in a preemptive-scheduling multi-tasking application due to the possibility of a timing race. Such applications must be written so that only one process accesses the stream, or to have a higher level lock. Since MAIL operations will not finish until they are completed, a single-tasking application does not have to worry about this problem, except in the callback invoked from MAIL (e.g. mm_exists(), etc.) in which case the stream is *always* locked. c-client Structures c-client has a large number of structures which are used for multiple functions. The most important of these are described here. The MAILSTREAM structure is used to reference open mailboxes. Applications may reference the following: char *mailbox; mailbox name unsigned short use; stream use count, this is incremented unsigned short sequence; stream sequence, this is incremented each time a stream is reused (i.e. mail_open() is called to open a different mailbox on this stream) unsigned int rdonly : 1; stream is open read-only unsigned int anonymous : 1; stream is open with anonymous access unsigned int halfopen : 1; stream is half-open; it can be reopened or used for functions that don't need a open mailbox such as mail_create() but no message data can be fetched unsigned int perm_seen : 1; Seen flag can be set permanently unsigned int perm_deleted : 1; Deleted flag can be set permanently unsigned int perm_flagged : 1; Flagged flag can be set permanently unsigned int perm_answered :1; Answered flag can be set permanently unsigned int perm_draft : 1; Draft flag can be set permanently unsigned int kwd_create : 1; new user flags can be created by referencing then in mail_setflag() or mail_clearflag(). Note: this can change during a session (e.g. if there is a limit on the number of keywords), so check after creating a new flag to see if any more can be created before letting the user try to do so unsigned long perm_user_flags; corresponding user flags can be set permanently. This is a bit mask which matches the entries in stream->user_flags[] unsigned long gensym; generated unique value. Always referenced with stream->gensys++ unsigned long nmsgs; number of messages in current mailbox unsigned long recent; number of recent messages in current mailbox unsigned long uid_validity; UID validity value; this is used to verify that recorded UIDs match the UIDs that the stream has. If the mailbox does not have matching UIDs (e.g. the UIDs were lost or not recorded) then the UID validity value will be different unsigned long uid_last; highest currently assigned UID in the current mailbox; a new UID will be assigned with ++stream->uid_last char *user_flags[NUSERFLAGS]; pointers to user flag names in bit order from stream->perm_user_flags or elt->user_flags The following MAILSTREAM values are only used internally: DRIVER *dtb; dispatch table for this driver void *local; pointer to driver local data unsigned int lock : 1; stream lock flag (an operation is in progress; used as a bug trap to detect recursion back to c-client from callback routines). unsigned int debug : 1; debugging information should be logged via mm_dlog(). unsigned int silent : 1; don't do main program callbacks on this stream (used when a stream is opened internally) unsigned int scache : 1; short caching; don't cache information in memory The following MAILSTREAM values are only used by the cache manager routine (see the documentation about mailcache_t above): unsigned long cachesize; size of c-client message cache union { void **c; to get at the cache in general MESSAGECACHE **s; message cache array LONGCACHE **l; long cache array } cache; 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 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 data pointer to driver-dependent data, from which the driver can determine string data size size of the string This method initializes the string stucture. It can use the data, data1, and chunksize values as it likes. The remaining values must be set up as follows: size static, copied from the size argument chunk pointer to a buffer loaded with initial data chunksize size of the buffer offset 0 curpos copied from chunk cursize copied from chunksize dtb STRINGDRIVER identity pointer char (*next) (STRING *s); s pointer to the string structure This method returns the character at the current string character pointer, and increments the string character pointer. This method is likely to call the setpos method if the desired character is not in the current chunk. 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. If the pointer is not in the current chunk, then a new chunk is loaded and the associated values (chunk, offset, curpos, cursize) are adjusted accordingly. 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 Structures" 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 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 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() 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 space. 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. 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) char *mail_fetchtext (MAILSTREAM *stream,unsigned long msgno); char *mail_fetchtext_full (MAILSTREAM *stream,unsigned long msgno, unsigned long *len,long flags); stream stream to fetch on msgno message sequence number len returned length in octets flags option flags This function causes a fetch of the non-header text of the specified message as a text string and returns that text string. No attempt is made to segregate individual body parts. 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_fetchtext_full() are a bit mask with one or more of the following: FT_UID The msgno argument is a UID FT_PEEK Do not set the \Seen flag if it not already set FT_INTERNAL The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines char *mail_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *sec, unsigned long *len); char *mail_fetchbody_full (MAILSTREAM *stream,unsigned long msgno,char *sec, unsigned long *len,long flags); stream stream to fetch on msgno message sequence number sec section specifier len returned length in octets flags option flags This function causes a fetch of the particular section of the body of the specified message as a text string and returns that text string. The section specification is a string of integers delimited by period which index into a body part list as per the IMAP4 specification. Body parts are not decoded by this function; see rfc822_base64() and rfc822_quotedprintable(). 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 may return NIL on error. The options for mail_fetchbody_full() are a bit mask with one or more of the following: FT_UID The msgno argument is a UID FT_PEEK Do not set the \Seen flag if it not already set FT_INTERNAL The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines unsigned long mail_uid (MAILSTREAM *stream,unsigned long msgno); stream stream to fetch on msgno message sequence number This function returns the UID for the given message sequence number. void mail_fetchfrom (char *s,MAILSTREAM *stream,unsigned long msgno, long length); s destination string stream stream to fetch on msgno message sequence number length maximum field length This function writes a "from" string of the specified length for the specified message, suitable for display to the user in a menu line, into the string pointed to by s. If the personal name of the first address in the envelope's from item is non-NIL, it is used; otherwise a string is created by appending the mailbox of the first address, an "@", and the host of the first address. The string is trimmed or padded with trailing spaces as necessary to make its length match the length argument. void mail_fetchsubject (char *s,MAILSTREAM *stream,unsigned long msgno, long length); s destination string stream stream to fetch on msgno message sequence number length maximum field length This function returns a "subject" string of the specified length for the specified message, suitable for display to the user in a menu line. The envelope's subject item is copied and trimmed as necessary to make its length be no more what the caller requested. Unlike mail_fetchfrom(), this function can return a string of shorter length than what the caller requested. LONGCACHE *mail_lelt (MAILSTREAM *stream,unsigned long msgno); MESSAGECACHE *mail_elt (MAILSTREAM *stream,unsigned long msgno); stream stream to access msgno message sequence number This function returns the cache entry for the specified message. Although it will create a cache entry if it does not already exist, that functionality is for internal use only. This function should never be called without having first called mail_fetchfast() or mail_fetchstructure() on the message first. A cache entry holds the internal date/time, flags, and RFC 822 size of a message. It holds other data as well, but that is for internal use only. mail_lelt() is a variant that returns a `long' cache entry, which consists of an cache entry (as a structure, not a pointer), an envelope pointer, and a body pointer. This is used in conjunction with the elt lock count functionality, to allow an application to associate the cached envelope and body of a message with an open window even if the message is subsequently expunged or if the stream is closed. Unless your application wants to look at cached envelopes and bodies even after the message is expunged or the stream is closed, it should not use mail_lelt(). Instead, it should use a returned elt from mail_elt() and use the elt->msgsno as the argument to mail_fetchstructure(). BEWARE: the behavior of mail_lelt() is undefined if the stream is open with OP_SHORTCACHE. mail_lelt() is extremely special purpose, and should only be used in sophisticated special purpose applications after discussing its use with the c-client author. If you think you need this function, you are probably mistaken. In almost all cases, you should use mail_elt() and mail_fetchstructure() instead. Message Status Manipulation Functions void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag); void mail_setflag_full (MAILSTREAM *stream,char *sequence,char *flag, long flags); stream stream to use sequence IMAP-format set of message sequence numbers flag IMAP-format flag string flags option flags This function causes a store to add the specified flag to the flags set for the messages in the specified sequence. If there is any problem in setting flags, a message will be passed to the application via the mm_log() facility. The options for mail_setflag_full() are a bit mask with one or more of the following: ST_UID The sequence argument contains UIDs instead of sequence numbers ST_SILENT Do not update the local cache with the new value of the flags. This is useful to save network bandwidth, at the cost of invalidating the cache. void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag); void mail_clearflag_full (MAILSTREAM *stream,char *sequence,char *flag, long flags); stream stream to use sequence IMAP-format set of message sequence numbers flag IMAP-format flag string flags option flags This function causes a store to delete the specified flag from the flags set for the messages in the specified sequence. If there is any problem in clearing flags, a message will be passed to the application via the mm_log() facility. The options for mail_setflag_full() are a bit mask with one or more of the following: ST_UID The sequence argument contains UIDs instead of sequence numbers ST_SILENT Do not update the local cache with the new value of the flags. This is useful to save network bandwidth, at the cost of invalidating the cache. Mailbox Searching void mail_search (MAILSTREAM *stream,char *criteria); void mail_search_full (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm, long flags); stream stream to search charset MIME character set to use when searching strings pgm search program flags option flags This function causes a mailbox search, using the given MIME charset (NIL means the default, US-ASCII) and the given search program. A search program is a structure that holds the following data: SEARCHSET *msgno; a set of message sequence numbers SEARCHSET *uid; a set of unique identifiers SEARCHOR *or; OR result of two search programs SEARCHPGMLIST *not; AND result of list of NOT'ed search programs SEARCHHEADER *header; message headers STRINGLIST *bcc; string(s) appear in bcc list STRINGLIST *body; string(s) appear in message body text STRINGLIST *cc; string(s) appear in cc list STRINGLIST *from; string(s) appear in from STRINGLIST *keyword; user flag string(s) set STRINGLIST *unkeyword; user flag strings() not set STRINGLIST *subject; string(s) appear in subject STRINGLIST *text; string(s) appear in message header or body STRINGLIST *to; string(s) appear in to list unsigned long larger; larger than this many octets unsigned long smaller; smaller than this many octes The following dates are in form: ((year - BASEYEAR) << 9) + (month << 5) + day unsigned short sentbefore; sent before this date unsigned short senton; sent on this date unsigned short sentsince; sent since this date unsigned short before; received before this date unsigned short on; received on this date unsigned short since; received since this date unsigned int answered : 1; message answered unsigned int unanswered : 1; message not answered unsigned int deleted : 1; message deleted unsigned int undeleted : 1; message not deleted unsigned int draft : 1; message is a draft unsigned int undraft : 1; message is not a draft unsigned int flagged : 1; message flagged as urgent unsigned int unflagged : 1; message not flagged as urgent unsigned int recent : 1; message recent since last parse of mailbox unsigned int old : 1; message not recent since last parse of mailbox unsigned int seen : 1; message read unsigned int unseen : 1; message not read The following auxillary structures are used by search programs: SEARCHHEADER: header line searching char *line; header line field name char *text; text header line SEARCHHEADER *next; next SEARCHHEADER in list (AND'ed) SEARCHSET: message number set unsigned long first; first number in set unsigned long last; if non-zero, last number in set SEARCHSET *next; next SEARCHSET in list (AND'ed) SEARCHOR: two search programs, OR'ed together SEARCHPGM *first; first program SEARCHPGM *second; second program SEARCHOR *next; next SEARCHOR in list SEARCHPGMLIST: list of search programs SEARCHPGM *pgm; search program (AND'd with others in list) SEARCHPGMLIST *next; next SEARCHPGM in list mail_search(), the older interface, accepts a search criteria argument as a character string in IMAP2 (RFC-1176) format. Do not try to use any IMAP4 search criteria with this interface. The application's mm_searched() function is called for each message that matches the search criteria. In addition, after the search is completed, the "fast" information (see mail_fetchfast_full() and envelopes of the searched messages are fetched (this is called pre-fetching). If there is any problem in searching, a message will be passed to the application via the mm_log() facility. The flags for mail_search_full() are a bit mask with one or more of the following: SE_UID Return UIDs instead of sequence numbers SE_FREE Return the search program to free storage after finishing SE_NOPREFETCH Don't prefetch searched messages. unsigned long *mail_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg, SORTPGM *pgm,long flags); stream stream to sort charset MIME character set to use when sorting strings spg search program pgm sort program flags option flags This function is a variant of mail_search_full(). It accepts an additional argument, a sort program, which specifies one or more sort rules to be applied to the result. If the searching and sorting are successful, it returns a 0-terminated vector of message sequence numbers (or UIDs if SE_UID is set). This vector is created out of free storage, and must be freed with fs_give() when finished with it. A sort program is a structure that holds the following data: unsigned int reverse : 1; reverse sorting of this key short function; sort rule, one of the following: SORTDATE message Date SORTARRIVAL arrival date SORTFROM mailbox in first From address SORTSUBJECT message Subject SORTTO mailbox in first To address SORTCC mailbox in first cc address SORTSIZE size of message in octets SORTPGM *next; next sort program to be applied if two or more messages collate identically with this rule The flags for mail_search_full() are a bit mask with one or more of the following: SE_UID Return UIDs instead of sequence numbers SE_FREE Return the search program to free storage after finishing SE_NOPREFETCH Don't prefetch searched messages. SO_FREE Return the sort program to free storage after finishing Miscellaneous Mailbox and Message Functions long mail_ping (MAILSTREAM *stream); stream string to ping The function pings the stream to see if it is still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a "keep alive" for servers which have an inactivity timeout. It returns T if the stream is still alive, NIL otherwise. If new mail is found, the application's mm_exists() function is called with the newly-determined number of messages in the mailbox. void mail_check (MAILSTREAM *stream); stream stream to checkpoint This function causes a mailstore-defined checkpoint of the mailbox. This may include such things as a writeback to disk, a check for flag changes in a shared mailbox, etc. It is not a "check for new mail"; mail_ping() performs this function (as potentially does any other function). The status of the check is passed to the application via the mm_log() facility. void mail_expunge (MAILSTREAM *stream); stream string to expunge This function causes an expunge (permanent removal of messages which are marked as deleted) of the mailbox. The application's mm_expunged() function is called for each message that has been expunged. The application's mm_exists() function is called at the start and end of the expunge to ensure synchronization. The status of the expunge is passed to the application via the mm_log() facility. Note that the decrementing of msgno's for subsequent messages happens immediately; for example, if three consequtive messages starting at msgno 5 are expunged, mm_expunged() will be called with a msgno of 5 three times. long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox); long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox); long mail_copy_full (MAILSTREAM *stream,char *sequence,char *mailbox, long options); stream stream to copy sequence IMAP-format set of message numbers mailbox destination mailbox name options option flags This function causes the messages in the specified sequence to be copied to the specified mailbox. T is returned if the copy is successful. mail_move() is equivalent to setting CP_MOVE in the options. If there is any problem in copying, a message will be passed to the application via the mm_log() facility and the function returns NIL. No copying is actually done in this case. Note that the mailbox must be on the same host as the stream and is a mailbox of the type of the source mailbox only. The flags for mail_search_full() are a bit mask with one or more of the following: CP_UID The sequence argument contains UIDs instead of sequence numbers CP_MOVE Delete the messages from the current mailbox after copying to the destination. long mail_append (MAILSTREAM *stream,char *mailbox,STRING *message); long mail_append_full (MAILSTREAM *stream,char *mailbox,char *flags,char *date, STRING *message); stream stream to use if non-NIL (in the IMAP case) mailbox destination mailbox name flags flags to set on message if non-NIL date internal date (received date) to set on message if non-NIL message string structure of message to write This function writes the message in the string structure to the destination mailbox, along with the flags and date if specified. This is useful in those cases where you can't use mail_copy(), e.g. when copying from one server to another; you can always fetch the message and then mail_append() it to the destination. It may also be useful for maintaining an outbox of your outgoing mail. void mail_gc (MAILSTREAM *stream,long gcflags); stream stream to GC if non-NIL (else GC's all streams) flags option flags This function garbage collects (purges) the cache of entries of a specific type. Some drivers do not allow purging of particular cache types, and an attempt to do so is ignored. The flags for mail_gc() are a bit mask with one or more of the following: GC_ELT message cache elements GC_ENV ENVELOPEs and BODYs GC_TEXTS cached texts Date/Time Handling Functions char *mail_date (char *string,MESSAGECACHE *elt); string destination string elt message cache element containing date This function accepts a message cache element that contains date information, and writes an IMAP-4 date string, that is, one in form: dd-mmm-yyyy hh:mm:ss +zzzz based upon the data in the elt. The destination string must be large enough to hold this string. char *mail_cdate (char *string,MESSAGECACHE *elt); string destination string elt message cache element containing date This function accepts a message cache element that contains date information, and writes a ctime() format date string, that is, one in form: www mmm dd hh:mm:ss yyyy\n based upon the data in the elt. The destination string must be large enough to hold this string. long mail_parse_date (MESSAGECACHE *elt,char *string); elt message cache element to store parsed date string source date string This function parses the date/time stored in the given string, in format: [www,] date [[hh:mm[:ss][-zzz| +zzzz] where the date can be any of: mm/dd/yy, mm/dd/yyyy, dd-mmm-yy, dd-mmm-yyyy, dd mmm yy, dd mmm yyyy and stores the result of the parse in the elt. If the parse is successful, T is returned, else NIL. unsigned long mail_longdate (MESSAGECACHE *elt); elt message cache element containing date. This function accepts a message cache element that contains date information, and returns the number of days since the base time of the imap-4 toolkit. At present, this is the same as the Unix time() value for that date/time, and hence can be used for functions such as utime(). Utility Functions void mail_debug (MAILSTREAM *stream); stream stream to debug This function enables telemetry logging for this stream. All telemetry is passed to the application via the mm_dlog() facility. void mail_nodebug (MAILSTREAM *stream); stream stream to disable debugging This function disables telemetry logging for this stream. long mail_sequence (MAILSTREAM *stream,char *sequence); stream stream to set the sequence bits sequence IMAP-format message set string This function parses the given sequence string for message numbers, sets the sequence bit in the stream's message cache element of all messages in the sequence (and turns it off in all other message cache elements). If the parse is successful, T is returned, else NIL. long mail_uid_sequence (MAILSTREAM *stream,char *sequence); stream stream to set the sequence bits sequence IMAP-format message set string This function parses the given sequence string for unique identifiers, sets the sequence bit in the stream's message cache element of all messages in the sequence (and turns it off in all other message cache elements). If the parse is successful, T is returned, else NIL. long mail_parse_flags (MAILSTREAM *stream,char *flag,unsigned long *uf); stream stream (used to get user flags) flag IMAP-format flag string to parse uf returned location of user flags The function parses the given flag string, and returns the system flags as its return value and the user flags in the location pointed to by the uf argument. If there is an error in parse, a log message is issued via mm_log() and this function returns NIL. unsigned long mail_filter (char *text,unsigned long len,STRINGLIST *lines, long flags); text RFC 822 text to filter len length in octets in the text argument lines string list of header file names to filter flags option flags This function supports the header lines filtering function of mail_fetchheader_full(). The lines argument 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. The options for mail_filter() are a bit mask with one or more of the following: FT_NOT The returned header lines are those that are not in the lines argument long mail_search_msg (MAILSTREAM *stream,unsigned long msgno,char *charset, SEARCHPGM *pgm); stream stream to search msgno message number of message to inspect charset character set of search strings pgm search program to test This function implements mail_search_full() locally in cases when it is not done by a server (e.g. local mail files, NNTP/POP). It inspects the given message on that stream to see if it matches the criteria or not. If it matches, T is returned, else NIL. SEARCHPGM *mail_criteria (char *criteria); criteria IMAP2-format search criteria string This function accepts an IMAP2-format search criteria string and parses it. If the parse is successful, it returns a search program suitable for use in mail_search_full(). WARNING: This function does not accept IMAP4 search criteria. The source string must be writeable (this restriction was also in the old IMAP2 c-client). Data Structure Instantiation/Destruction functions These functions are used to obtain structures from free storage and to release them. ENVELOPE *mail_newenvelope (void); ADDRESS *mail_newaddr (void); BODY *mail_newbody (void); BODY *mail_initbody (BODY *body); PARAMETER *mail_newbody_parameter (void); PART *mail_newbody_part (void); STRINGLIST *mail_newstringlist (void); SEARCHPGM *mail_newsearchpgm (void); SEARCHHEADER *mail_newsearchheader (char *line); SEARCHSET *mail_newsearchset (void); SEARCHOR *mail_newsearchor (void); SEARCHPGMLIST *mail_newsearchpgmlist (void); SORTPGM *mail_newsortpgm (void); These functions, all named mail_new...(), create a new structure of the given type and initialize all of its elements to zero or empty. void mail_free_body (BODY **body); void mail_free_body_parameter (PARAMETER **parameter); void mail_free_body_part (PART **part); void mail_free_cache (MAILSTREAM *stream); void mail_free_elt (MESSAGECACHE **elt); void mail_free_lelt (LONGCACHE **lelt); void mail_free_envelope (ENVELOPE **env); void mail_free_address (ADDRESS **address); void mail_free_stringlist (STRINGLIST **string); void mail_free_searchpgm (SEARCHPGM **pgm); void mail_free_searchheader (SEARCHHEADER **hdr); void mail_free_searchset (SEARCHSET **set); void mail_free_searchor (SEARCHOR **orl); void mail_free_searchpgmlist (SEARCHPGMLIST **pgl); void mail_free_sortpgm (SORTPGM **pgm); These functions, all named mail_free_...(), take a pointer to a structure pointer, free all contained strings and structures within the structure, and finally free the structure itself and set its pointer to NIL. For example, mail_free_envelope() frees all the ADDRESS structures contained in the envelope. Normally, mail_free_elt() and mail_free_lelt() are used only if the main program has a private pointer to cache elements. If so, it is expected to increment the cache element's lockcount when it makes a private pointer, and to call this function when it is finished with it. Authentication Functions char *mail_auth (char *mechanism,authresponse_t resp,int argc,char *argv[]); mechanism authentication mechanism name resp callback function for providing responses argc main() function argc value argv main() function argv value This server function searches the list of authenticators that was established by auth_link() for an authenticator with the given name. If an authenticator is found, authentication is initialized. The function pointed to by resp is called as the authenticator requires responses. AUTHENTICATOR *mail_lookup_auth (unsigned int i); i position in authenticator list This function returns the nth authenticator in the list, where n is the value of it. unsigned int mail_lookup_auth_name (char *mechanism); mechanism authentication mechanism name This function searches the list of authenticators for an authenticator with the given name, and returns its position in the authenticator list. The functions below are provided by c-client client drivers or by servers to support the protocol-dependent parts of authentication. typedef void *(*authchallenge_t) (void *stream,unsigned long *len); stream stream to read challenge len pointer to returned length in octets This driver function is called by an authenticator to read a challenge from the given protocol stream in a protocol-dependent way. It returns that challenge in binary and its length in octets to the authenticator. typedef long (*authrespond_t) (void *stream,char *s,unsigned long size); stream stream to send response s response string size length of response string in octets This driver function is called by an authenticator to send a challenge response to the given stream in a protocol-dependent way. It returns T if successful, NIL if failure. typedef char *(*authresponse_t) (void *challenge,unsigned long clen, unsigned long *rlen); challenge challenge string clen length of challenge string in octets rlen pointer to returned length of response string This server function is called with a challenge string of clen octets. It sends, according to whatever protocol (IMAP, POP, etc.) it uses, and returns the received response and response length in octets. typedef long (*authclient_t) (authchallenge_t challenger, authrespond_t responder,NETMBX *mb,void *s, unsigned long trial); challenger pointer to protocol-dependent challenge reader function responder pointer to protocol-dependent response sender function mb NETMBX struct of the mailbox desired to open s stream for protocol-dependent routines to use trial number of authentication attempts remaining This client authenticator function negotiates reading challenges and sending responses for a particular authenticator (Kerberos, etc.) over the protocol, and returns T if authenticated or NIL if failed. typedef char *(*authserver_t) (authresponse_t responder,int argc,char *argv[]); responder pointer to protocol-dependent responder function argc main() function argc value argv main() function argv value This server authenticator function negotiates sending challenges and reading responses for a particular authenticator (Kerberos, etc.), and returns either the authenticated user name or NIL if authentication failed. Network Access Functions These functions provide a layer of indirection between the TCP routines and upper level routines. This makes it possible to insert additional code (e.g. privacy or checksum handling). NETSTREAM *net_open (char *host,char *service,unsigned long port); host host name service contact service name port contact port number This function opens a TCP connection to the given host and service or port. NETSTREAM *net_aopen (NETMBX *mb,char *service,char *usrbuf); NETMBX parsed mailbox specification service stream to open (at present, only /etc/rimapd is used) usrbuf buffer to return login user name This function attempts to open a preauthenticated connection to the given mailbox and service. It will return the login user name of the preauthenticated connection, as well as an open network stream, if successful. char *net_getline (NETSTREAM *stream); stream network stream to read This routine reads a text line from the stream. It calls stream->dtb->getline, which normally points to tcp_getline() but can be set to some other function. long net_getbuffer (void *stream,unsigned long size,char *buffer); stream network stream to read size length of data in octets buffer buffer of at least size octets This routine reads data from the stream. It calls stream->dtb->getbuffer, which normally points to tcp_getbuffer() but can be set to some other function. long net_soutr (NETSTREAM *stream,char *string); stream network stream to write string null-terminated string to output This routine writes a null-terminated string to the stream. It calls stream->dtb->soutr, which normally points to tcp_soutr() but can be set to some other function. long net_sout (NETSTREAM *stream,char *string,unsigned long size); stream network stream to write string string to output size length of string in octets This routine writes a string of length size to the stream. It calls stream->dtb->sout, which normally points to tcp_sout() but can be set to some other function. void net_close (NETSTREAM *stream); stream stream to close This routine closes the stream. It calls stream->dtb->close, which normally points to tcp_close() but can point to some other function. char *net_host (NETSTREAM *stream); stream stream to inspect This routine returns the remote host name of the stream. It calls stream->dtb->host, which normally points to tcp_host() but can point to some other function. unsigned long net_port (NETSTREAM *stream); stream stream to inspect This routine returns the remote port number of the stream. It calls stream->dtb->port, which normally points to tcp_port() but can point to some other function. char *net_localhost (NETSTREAM *stream); stream stream to inspect This routine returns the local host name of the stream. It calls stream->dtb->localhost, which normally points to tcp_localhost() but can point to some other function. Subscription Management Functions long sm_subscribe (char *mailbox); mailbox mailbox name to subscribe This function adds the given mailbox name to the local subscription list, and returns T if successful, NIL if failure. long sm_unsubscribe (char *mailbox); mailbox mailbox name to unsubscribe This function removes the given mailbox name from the local subscription list, and returns T if successful, NIL if failure. char *sm_read (void **sdb); sdb data to use in subsequent calls, or NIL if first call This function returns the local subscription list as null terminated strings. Each call returns the next element in the list. The first call should be with sdb pointing to a NIL pointer; this will be filled in for subsequent calls. At the last call, NIL will be returned. Miscellaneous Utility Functions char *ucase (char *string); string string to convert This function converts each lowercase character of the specified string to uppercase and returns the string. char *lcase (char *string); string string to convert This function converts each uppercase character of the specified string to lowercase and returns the string. char *cpystr (char *string); string string to copy This function makes a copy of the string from free storage and returns the copy. long find_rightmost_bit (long *valptr); valptr pointer to value to search This function returns -1 if the 32-bit value pointed to by valptr is non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of the right-most bit in that value. This is used to convert from the bits in the cache's userflags item to an index into the stream's userFlags array of flag texts. long min (long i,long j); i first argument j second argument This function returns the minimum of the two integers. long max (long i,long j); i first argument j second argument This function returns the maximum of the two integers. long search (char *s,long c,char *pat,long patc); s string to search c size of string pat pattern to search in string patc size of pattern This function does a fast case-independent search for the given pattern in pat (length patc) in base string s, and returns T if the pattern is found in the string. long pmatch (char *s,char *pat,delim); long pmatch_full (char *s,char *pat,delim); s string to match pat wildcard (* and %) to match in pattern delim hierarchy delimiter This function returns T if the given wildcard pattern matches the string in s with hierarchy delimiter delim. Otherwise NIL is returned. long dmatch (char *s,char *pat,char delim); s string to match pat wildcard (* and %) to match in pattern delim hierarchy delimiter This function returns T if the given wildcard pattern matches the directory. If not, then none of the elements in the directory are considered for recursive checking with pmatch_full(). SMTP Functions SMTPSTREAM *smtp_open (char **hostlist,long debug); hostlist vector of SMTP server host names to try debug non-zero if want protocol telemetry debugging This function opens an SMTP connection to a one of the hosts in the host list and if successful returns a stream suitable for use by the other SMTP functions. The hosts are tried in order until a connection is successfully opened. If debug is non-NIL, protocol telemetry is logged via mm_dlog(). NIL is returned if this function fails to open a connection to any of the hosts in the list. void smtp_close (SMTPSTREAM *stream); stream stream to close This function closes the SMTP stream and frees all resources associated with it that it may have created. long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body); stream stream to transmit mail type mail type (MAIL, SEND, SAML, SOML) msg message envelope body message body This function negotiates an SMTP transaction of the specified type (one of "MAIL", "SEND", "SAML", or "SOML") to deliver the specified message. This function returns T if success or NIL if there is any failure. The text reason for the failure is in stream->reply item; if it is associated with a recipient it is also in that address' address->error item. void smtp_debug (SMTPSTREAM *stream); stream stream to enable debugging telemetry This function enables SMTP protocol telemetry logging for this stream. All SMTP protocol operations are passed to the application via the mm_dlog() facility. void smtp_nodebug (SMTPSTREAM *stream); stream stream to disable debugging telemetry This function disables SMTP protocol telemetry logging for this stream. typedef void (*smtpverbose_t) (char *buffer); buffer pointer to verbose reply buffer This is the argument to the SET_SMTPVERBOSE mail_parmameter() call. If this function pointer is non-NIL, then if a verbose SMTP response (with SMTP code less than 100) is received, this function is called with that response text as its argument. NNTP Functions NNTPSTREAM *nntp_open (char **hostlist,long debug); hostlist vector of NNTP server host names to try debug non-zero if want protocol telemetry debugging This function opens an NNTP connection to a one of the hosts in the host list and if successful returns a stream suitable for use by the other MTP functions. The hosts are tried in order until a connection is successfully opened. If debug is non-NIL, protocol telemetry is logged via mm_dlog(). NIL is returned if this function fails to open a connection to any of the hosts in the list. void nntp_close (NNTPSTREAM *stream); stream stream to close This function closes the NNTP stream and frees all resources associated with it that it may have created. long nntp_mail (NNTPSTREAM *stream,ENVELOPE *msg,BODY *body); stream stream to transmit mail msg message envelope body message body This function negotiates an NNTP posting transaction to deliver the specified news message. This function returns T if success or NIL if there is any failure. The text reason for the failure is in stream->reply item; if it is associated with a recipient it is also in that address' address->error item. RFC 822 Support Functions Although rfc822.c contains several additional functions besides these, only the functions documented here should be used by applications. The other functions are for internal use only. void rfc822_header (char *header,ENVELOPE *env,BODY *body); header buffer to write RFC 822 header env message ENVELOPE (used to obtain RFC 822 information) body message BODY (used to obtain MIME information) This function writes an RFC 822 format header into header based on the information in the envelope and body. The header buffer must be large enough to contain the full text of the resulting header. void rfc822_write_address (char *dest,ADDRESS *adr); dest buffer to write address list adr RFC 822 ADDRESS list This function writes an RFC 822 format address list into dest based on the information in adr. The dest buffer must be large enough to contain the full text of the resulting address list. void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i, STRING *b,char *host,char *tmp); en destination pointer where message ENVELOPE will be stored bdy destination pointer where message BODY will be stored s RFC 822 header to parse (character string) i length of RFC 822 header b stringstruct of message body host default host name if an address lacks an @host. temp scratch buffer, must be long enough to hold unwound header lines (a buffer that is i octets long is OK) This function parses the RFC 822 header pointed to by s with body pointed to by string structure b into the specified destination envelope and body pointers, using host as the default host name and tmp as a scratch buffer. New ENVELOPE and BODY structures are created; when finished with them the application must free them with mail_free_envelope() and mail_free_body(). Any parsing errors are noted via the mm_log() mechanism using log type PARSE. void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host); lst destination pointer where ADDRESS will be stored string string of addresses to parse host default host name if an address lacks an @host. This function parses the address list in the given string into an address list in lst. Any addresses missing a host name are have the host name defaulted from the host argument. If the destination list is non-empty it appends the new addresses to the list. Any parsing errors are noted via the mm_log() mechanism using log type PARSE. long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,void *s, long ok8bit); t scratch buffer, large enough to hold message header env message ENVELOPE body message BODY f I/O function to write to s stream for I/O function f ok8bit non-zero if OK to output 8-bit data This function writes the message described with the given envelope and body. Any body part contents of type ENCBINARY is converted to ENCBASE64 before sending. If ok8bit is NIL, any message data of type ENC8BIT is converted to ENCQUOTEDPRINTABLE before sending; if ok8bit is non-NIL then ENC8BIT data is sent as-is. T is returned if the function succeeds, else NIL is returned. The function f is typically net_soutr(), but it can be any function which matches typedef long (*soutr_t) (void *stream,char *string); where stream holds sufficient information to enable the output routine to know where to output to, and the string is a null-terminated string to output. This function returns either T or NIL, and that value is passed up to rfc822_output() for its return. void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len); src source string srcl size of source string in octets len pointer to where destination string length in octets will be returned This function decodes a BASE64 body part given a source string and its length. The decoded body part as a sequence of binary octets is returned, and its length is returned in len. char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len); src source string srcl size of source string in octets len pointer to where destination string length in octets will be returned This function decodes a QUOTED-PRINTABLE body part given a source string and its length. The decoded body part as an 8-bit character string is returned, and its length is returned in len. Operating System-Dependent Public Interface These functions are in OS-dependent code, and are rewritten each time c-client is ported to a new operating system. void rfc822_date (char *date); date buffer to write the date, must be large enough This function is called to get the current date and time in an RFC 822 format string into the given buffer. void *fs_get (size_t size); size number of octets requested This function allocates and returns a block of free storage of the specified size. Unlike malloc(), there is no failure return; this function must return with the requested storage. void fs_resize (void **block,size_t size); block pointer to pointer to block to be resized size new size in octets This function resizes the free storage block, updating the pointer if necessary. Unlike realloc(), there is no failure return; this function must return with the requested storage. void fs_give (void **block); block pointer to pointer to block to free This function releases a block of free storage allocated by fs_get(). It also erases the block pointer, so it isn't necessary to do this in the application. void fatal (char *string); string message string This function is called when an "impossible" error is detected and the client wishes to crash. The string should contain a reason. char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl); dst pointer to destination string pointer dstl pointer to destination string size src source strin srcl source string size This function is called to copy into a destination string dst of size dstl (resized if necessary), a CRLF newline form string from local format string src of size srcl. TCPSTREAM *tcp_open (char *host,long port); TCPSTREAM *tcp_aopen (char *host,char *service); char *tcp_getline (TCPSTREAM *stream); long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer); long tcp_soutr (TCPSTREAM *stream,char *string); void tcp_close (TCPSTREAM *stream); char *tcp_host (TCPSTREAM *stream); unsigned long tcp_port (TCPSTREAM *stream); char *tcp_localhost (TCPSTREAM *stream); These functions are TCP-specific versions of the more general net_xxx() functions. These should not be called directly by applications. char *tcp_clienthost (char *dst); dst destination string buffer This function should be called only by a server called by inetd or similar mechanism which maps standard input to a network socket. It returns the host name of the other end (e.g. the client of a server) using the given string buffer, or NIL if it can't get this information. Main Program Callbacks All applications which use the c-client must have the following callbacks to handle events from c-client. Note that in any callback which involves a mail stream, the stream is locked and you can not recursively call c-client from the callback. This may also be true in callbacks which do not have a stream; in general, the rule is "do not call c-client, especially any mail_xxx() function, from a c-client callback". void mm_flags (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called when c-client manipulates the flags for the given message number. This alerts the application that it may need to inspect that message's flags to see if there are any interesting changes. void mm_status (MAILSTREAM *stream,char *mailbox,MAILSTATUS *status); stream stream where event happened mailbox mailbox name for this status status MAILSTATUS structure with message status This function is called when c-client reports status of a mailbox (generally as the result of a mail_status() function call). The returned MAILSTATUS structure has the following members: long flags; validity flags. These are the same as the SA_xxx option flags in the mail_status() call, and they indicate which of the other members of the MAILSTATUS structure have usable data (i.e. if SA_MESSAGES is not set, do not believe status->messages!!). unsigned long messages; number of messages if SA_MESSAGES unsigned long recent; number of recent messages if SA_RECENT unsigned long unseen; number of unseen messages if SA_UNSEEN unsigned long uidnext; next UID to be assigned if SA_UIDNEXT unsigned long uidvalidity; UID validity value if SA_UIDVALIDITY void mm_searched (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called to notify the main program that this message number matches a search (generally as the result of a mail_search_full() function call). void mm_exists (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called to notify the main program that there are this many messages in the mailbox. It is also used to notify the main program of new mail, by announcing a higher number than the main program was previously aware. void mm_expunged (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called to notify the main program that this message number has been expunged from the mail file and that all subsequent messages are now referenced by a message number one less than before. This implicitly decrements the number of messages in the mailbox. void mm_list (MAILSTREAM *stream,char delim,char *name,long attrib); stream stream where event happened delim hierarchy delimiter name mailbox name attrib mailbox attributes This function is called to notify the main program that this mailbox name matches a mailbox listing request (generally as the result of a mail_list() function call). The hierarchy delimiter is a character that separates out levels of hierarchy in mailbox names. The attributes are a bit mask with one of the following: LATT_NOINFERIORS it is not possible for there to be any hierarchy inferiors to this name (that is, this name followed by the hierarchy delimiter and additional name characters). LATT_NOSELECT this is not a mailbox name, just a hierarchy level, and it may not be opened by mail_open() LATT_MARKED this mailbox may have recent messages LATT_UNMARKED this mailbox does not have any recent messages void mm_lsub (MAILSTREAM *stream,char delim,char *name,long attrib); stream stream where event happened delim hierarchy delimiter name mailbox name attrib mailbox attributes This function is called to notify the main program that this mailbox name matches a subscribed mailbox listing request (generally as the result of a mail_lsub() function call). The hierarchy delimiter is a character that separates out levels of hierarchy in mailbox names. The attributes are a bit mask with one of the following: LATT_NOINFERIORS it is not possible for there to be any hierarchy inferiors to this name (that is, this name followed by the hierarchy delimiter and additional name characters). LATT_NOSELECT this is not a mailbox name, just a hierarchy level, and it may not be opened by mail_open() LATT_MARKED this mailbox may have recent messages LATT_UNMARKED this mailbox does not have any recent messages void mm_notify (MAILSTREAM *stream,char *string,long errflg); stream stream where event happened string message string errflg message error level This function is called to deliver a stream-oriented message event. This is the mechanism by which any IMAP response codes for any application (e.g. TRYCREATE) are delivered to the application. No newline is included in the string, so this function has to output its own. The message error level is one of the following: NIL normal operation. The text is `babble' that may be interesting to the user, e.g. the greeting message from a server. WARN A warning event. This event should be displayed to the user. Examples: a mailbox rewrite failed because of disk full, but the previous mailbox contents were recovered. ERROR An error event. This event should be displayed to the user, or at least logged someplace. This type of error shouldn't happen, and so should be called to the attention of support staff. Whatever happened has probably disrupted the user's work. Examples: an untagged BAD from an IMAP server. void mm_log (char *string,long errflg); string message string errflg message error level This function is called to deliver a log message. No newline is included in the string, so this function has to output its own. In general, it is intended that these messages are logged someplace, and possibly shown to the user. The message error level is one of the following: NIL normal operation. The text is `babble' that may be interesting to the user, e.g. "Expunged 3 messages". PARSE An RFC 822 parsing error. Since bogus headers are all-too-common in the real world, these can often be ignored on the "garbage in, garbage out" princple. However, since surprising results can be yielded when trying to parse garbage, this message should be logged somewhere so it can be figured out what happened. WARN A warning event. This event should be displayed to the user. It occurs when an error condition has happened, but c-client knows what to do to recover. Examples: "Can't open read-write, so opening read-only", "Empty mailbox", "Login failed, try again", "Waiting for mailbox to become unlocked", "IMAP protocol error". Although a user should be told about a warning, it's generally not necessary to interrupt the flow of her work (e.g. it's alright to display the warning in a scrolling window, but not necessary to require the user to do anything). ERROR An error event. This event should be displayed to the user, or at least logged someplace. This is a serious error condition occured that aborted the requested operation and possibly also aborted the mail stream. This ranges from normal error conditions such as "Can't open mailbox", "too many login failures, go away" to bizarre conditions such as "Apparent new mail appeared in the mailbox that doesn't look like mail, program aborting". Errors must be called to the user's attention, and probably should require some sort of acknowledgement (e.g. answering a modal panel) before the application proceeds. void mm_dlog (char *string); string message string This function is called to deliver a debugging telemetry message. No newline is included in the string, so this function has to output its own. This is called only when debugging is enabled. void mm_login (NETMBX *mb,char *user,char *pwd,long trial); mb parsed mailbox specification user pointer to where to return user name pwd pointer to where to return password trial number of prior login attempts This function is called to get a user name and password for the given network mailbox. It stores the user name and password in the strings pointed to by the appropriate arguments. The trial argument is the number of attempts to perform the login and is initially zero (e.g. for a default username and password login functionality). It is incremented for each subsequent trial until the maximum number of trials are made. void mm_critical (MAILSTREAM *stream); stream stream where event happened This function is called to alert the application that c-client is about to run some critical code on that stream that may result in a clobbered mail file if it is interrupted. It may be desirable to disable CTRL/C, etc. during this time. void mm_nocritical (MAILSTREAM *stream); stream stream where event happened This function is called to alert the application that c-client is no longer running critical code on that stream that may result in a clobbered mail file if it is interrupted. long mm_diskerror (MAILSTREAM *stream,long errcode,long serious); stream stream where event happened errcode OS error code for disk error serious non-zero if c-client can not undo the operation (and thus must retry to avoid mail file damage) This function is called to alert the application that the c-client has encountered an unrecoverable write error when trying to update the mail file. errcode contains the system error code. If serious is non-zero, then it is probable that the disk copy of the mailbox has been damaged. The return value from this function is the abort flag; if serious is zero and the abort flag is non-zero, the operation is aborted. If the abort flag is zero or if serious was non-zero, a return from this function will retry the failing operation. void mm_fatal (char *string); string message string This function is called from the fatal() routine in the operating system code to notify the main program that it is about to crash. The string contains a reason. At the very minimum, the main program should do something like mm_log (string,ERROR); and then return. No newline is included in the string, so this function has to output its own. Driver interface When writing a new driver for the c-client, you must provide a DRIVER stucture giving a dispatch vector between MAIL and the driver. The DRIVER dispatch vector is described in mail.h. char *name; Name by which the driver is known to c-client. unsigned long flags; Attribute flags for this driver: DR_DISABLE This driver is currently disabled. DR_LOCAL This driver deals with local mailboxes; if this is off it deals with mailboxes over a network. DR_MAIL This driver supports e-mail messages. DR_NEWS This driver supports netnews messages DR_READONLY This driver only allows read-only access; mail_setflag(), mail_expunge(), etc. are no-ops. DR_NOFAST This driver does not implement mail_fetchfast() in a fast way (e.g. it may have to fetch the entire message text over a network to calculate sizes). DR_NAMESPACE This driver accepts and uses namespace format names. DR_LOWMEM This driver is designed for systems with very limited amounts of memory (e.g. DOS) and support routines called by this driver should try not to use much memory. DRIVER *next; Pointer to the next driver which this application supports (or NIL if this is the last driver). Drivers are lunk together via the mail_link() function. DRIVER *driver_valid (char *mailbox); This function returns a pointer to the driver's DRIVER dispatch vector iff this driver accepts the given name as a valid mailbox for this driver. Otherwise, it returns the value of the next driver's driver_valid() or NIL if there is no next driver. In other words, calling driver_valid() for the first driver will return the driver dispatch vector for the driver which supports this type of mailbox. void *driver_parameters (long function,void *value); This function implements mail_parameters() for this driver. void driver_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents); This function implements mail_scan() for this driver. void driver_list (MAILSTREAM *stream,char *ref,char *pat); This function implements mail_list() for this driver. void driver_lsub (MAILSTREAM *stream,char *ref,char *pat); This function implements mail_lsub() for this driver. long driver_subscribe (MAILSTREAM *stream,char *mailbox); This function implements mail_subscribe() for this driver. long driver_unsubscribe (MAILSTREAM *stream,char *mailbox); This function implements mail_unsubscribe() for this driver. long driver_create (MAILSTREAM *stream,char *mailbox); This function implements mail_create() for this driver. long driver_delete (MAILSTREAM *stream,char *mailbox); This function implements mail_delete() for this driver. long driver_rename (MAILSTREAM *stream,char *old,char *new); This function implements mail_rename() for this driver. long driver_status (MAILSTREAM *stream,char *mailbox,long flags); This function implements mail_status() for this driver. MAILSTREAM *driver_open (MAILSTREAM *stream); This function opens the mailbox identified by the given stream. It may use the data on the stream and create additional data on stream->local as necessary. It should return the given stream unless it failed to open the mailbox, in which case it should return NIL. void driver_close (MAILSTREAM *stream,long options); This function implements mail_close() for this driver. void driver_fetchfast (MAILSTREAM *stream,char *sequence,long flags); This function implements mail_fetchfast() for this driver. void driver_fetchflags (MAILSTREAM *stream,char *sequence,long flags); This function implements mail_fetchflags() for this driver. ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,unsigned long msgno, BODY **body,long flags); This function implements mail_fetchstructure() for this driver. char *driver_fetchheader (MAILSTREAM *stream,unsigned long msgno, STRINGLIST *lines,unsigned long *len,long flags); This function implements mail_fetchheader() for this driver. char *driver_fetchtext (MAILSTREAM *stream,unsigned long msgno, unsigned long *len,long flags); This function implements mail_fetchtext() for this driver. char *driver_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *section, unsigned long *len,long flags); This function implements mail_fetchbody() for this driver. void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag,long flags); This function implements mail_setflag() for this driver. void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag, long flags); This function implements mail_clearflag() for this driver. void driver_search (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm, long flags); This function implements mail_search() for this driver. unsigned long *driver_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg, SORTPGM *pgm,long flags); This function implements mail_sort() for this driver. void *driver_thread (MAILSTREAM *stream,char *seq,long function,long flag); This dispatch is reserved for a future threading capability. long driver_ping (MAILSTREAM *stream); This function implements mail_ping() for this driver. void driver_check (MAILSTREAM *stream); This function implements mail_check() for this driver. void driver_expunge (MAILSTREAM *stream); This function implements mail_expunge() for this driver. long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox, long options); This function implements mail_copy() for this driver. long driver_append (MAILSTREAM *stream,char *mailbox,char *flags,char *date, STRING *message); This function implements mail_append() for this driver. void driver_gc (MAILSTREAM *stream,long gcflags); This function implements mail_gc() for this driver. Driver Support Functions void mail_searched (MAILSTREAM *stream,unsigned long msgno); stream stream where event happened msgno message number This function is called by the driver to notify c-client that this message number matches a search. It invokes the main program's mm_searched() function. void mail_exists (MAILSTREAM *stream,unsigned long nmsgs); stream stream where event happened nmsgs number of messages This function is called by the driver to notify c-client that this message number exists (i.e. there are this many messages in the mailbox). It invokes the main program's mm_exists() function. void mail_recent (MAILSTREAM *stream,unsigned long recent); stream stream where event happened recent number of messages This function is called by the driver to notify c-client that this many messages are "recent" (i.e. arrived in the mailbox since the previous time the mailbox was opened). void mail_expunged (MAILSTREAM *stream,unsigned long msgno); stream stream where event happened msgno number of messages This function is called by the driver to notify MAIL that this message number has been expunged from the mail file and that all subsequent messages are now referenced by a message number one less than before. It invokes the main program's mm_expunged() function. void mail_lock (MAILSTREAM *stream); stream stream where event happened This function sets the stream lock. It is an error to set the stream lock if the stream is already locked. This is mainly used to catch errors due to a callback function (e.g. mm_exists) inadvertantly recursing back to the MAIL routines and establishing an infinite recursion. Normally, drivers will set the lock prior to calling one of the callback functions above or, more likely, in the beginning of the driver's non-reentrant "do operation" section. In the IMAP4 driver, the stream lock is set when entering imap_send() and cleared on exit. void mail_unlock (MAILSTREAM *stream); stream stream where event happened This function releases the stream lock. It is an error to release the stream lock if the stream is not locked.