This page describes tkbiff's programming interface to the engine
which actually reads the mail. If you want to construct an entirely
different GUI, this is the interface to use. In fact, you don't even
need a GUI interface. With the appropriate configuration file, tkbiff
can run as a background agent, perhaps communicating with another
program such as a database or a browser or yet other agents. tclbiff
provides a trivial example of this.
| mbox | name of mailbox |
| cfile | name of configuration file |
| sleep(file) | number of seconds to sleep before each check when using any file-based format (unless overridden by a specific file type, such as sleep(mbx)) |
| sleep(pop) | number of seconds to sleep before each check when using POP-based email |
| sleep(imap) | number of seconds to sleep before each check when using IMAP-based email |
| password | password |
| secret | apop secret |
| user | user name |
| verbose | 1 if verbose mode should be used, else 0 |
| verbosefile | if defined, a channel id for a log file for verbose messages (note that messages are logged whether or not verbose mode is on) |
| verbosefilename | if defined, log file name for verbose messages |
| hostretry | 1 if bad hosts should be ignored and later retried, else 0 |
| protocol(type) | imap, pop, mbox, mbx, or maildir |
| protocol(old) | 1 if additional work should be performed to report on old mail, else 0 |
| protocol(pop,maxlines) | max number of lines of per-message data to retrieve when
using POP. Useful with a slow connection. For no limit, use -1. Not
supported on POP servers that don't support the TOP command. |
| protocol(imap,maxchars) | max number of chars of per-message data to retrieve when using IMAP. Useful with a slow connection. For no limit, use -1. |
| protocol(imap,maxfetch) | max number of messages that can be fetched simultaneously from an IMAP server. |
| protocol(connectinit) | evaluated once before any connections have been made |
| protocol(connectpre) | evaluated before each connection is established |
| protocol(connect) | evaluated to establish the connection; evaluation should return a file identifier |
| protocol(connectpost) | evaluated after each connection is established |
| protocol(starttls) | evaluated to dynamically start TLS on an open connection. |
| protocol(preauth) | exists if the protocol is preauthorized. Only used for protocols that normally require authorization (i.e., pop and imap). |
| suppress_nfs_caching | if 1, NFS caching of mailboxes is suppressed, enabling tkbiff to see mailbox updates immediately on NFS-cached partitions; default is 0 which is much more efficient |
| fake_message_ids | if 1, message ids are faked if missing on IMAP or POP, which can potentially be expensive; default is 0, allowing such rare messages to be ignored which is more efficient |
| tkbiff(version) | version string of tkbiff |
| all_ids | array of all message ids in use. Element names are the message ids. Value is an integer defining the nth check upon which the message was last found. |
| all_list | list of all message ids in use |
| new_list | list of the new message ids read this cycle |
| recently_seen_ids | array of message ids recently seen but not currently in use. Element
names are the message ids. Values are integers defining the nth check
upon which messages were last found. This array allows the GUI to
remember (and not reannounce) mail that is temporarily gone which
occurs due to other mail software temporarily truncating a mail file
and then restoring it. |
| msg | array of message ids. Element names are of the form "id,headertype" where id is a message id and headertype is a header type such as from, to, cc, subject, or body. body is not an actual header but refers to the body of the message itself. The status element has the following values:| value | meaning | | NEW | message is new | | U | message is new and headers have been read but not body | | RO | message is old and has been read | | O | message is old and has not been read | | HIDE | message should not be displayed |
|
The following procedures are the only user-defined procedures that
tkbiff calls.
| init | called to initialize user environment. |
| announce_new_msgs | called when new mail is detected |
| renounce_msgs_ids | called when messages have disappeared (presumably the user
read them with some other mail client). The argument is a list containing the ids. The
message-specific data in the msg array is valid until this procedure
returns. |
| short_from | called to select the more pleasant parts of the From field for
purposes of display in a very short space. |
| user_password | called if the username, password, or secret are needed in
which case they should be stored in the global variables user,
password, and secret. user, password, and secret may be predefined. |
| busy | called whenever tkbiff is about to start doing something
time-consuming. The default tkbiff GUI uses this to change the shape
of the cursor. |
| idle | called when tkbiff is about to stop doing something
time-consuming. The default tkbiff GUI uses this to change the shape
of the cursor. |
| usage | called when arguments have been misused or are not recognized. When
not recognized, the arguments to be processed are left in argv. When
an error has been detected, it is passed as an argument. |
| verbose | called to handle tracing information such as by sending it to stdout, a trace window, and/or a log file |