|
|
All applications which use the C client interface must have the following callbacks to handle events from a C client. Note that in any callback involving a mail stream, the stream is locked and you can not recursively call the 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 a C client, especially any mail_xxx function, from a C client callback.
void mm_flags(MAILSTREAM *stream, unsigned long number);
This function is called when a 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);
This function is called when a 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 (that is, 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);
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);
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 that of which the main program was previously aware.
void mm_expunged(MAILSTREAM *stream, unsigned long 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);
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:
void mm_lsub(MAILSTREAM *stream, char delim, char *name, long attrib);
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:
void mm_notify(MAILSTREAM *stream, char *string, long errflg);
This function is called to deliver a stream-oriented message event. This is the mechanism by which any IMAP response codes for any application (for example, 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:
void mm_log(char *string, long errflg);
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:
Expunged 3 messages
.
Can't open read-write, so
opening read-only
, Empty mailbox
, Login failed,
try again
, Waiting for mailbox to become unlocked
,
and IMAP protocol error
. Although a user should be told
about a warning, it is generally not necessary to interrupt the
flow of work (for example, it's alright to display the warning
in a scrolling window, but not necessary to require the user to
do anything).
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 (for example, answering a modal panel)
before the application proceeds.
void mm_dlog(char *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);
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 (for example, 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);
This function is called to alert the application that the 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 and so on during this time.
void mm_nocritical(MAILSTREAM *stream);
This function is called to alert the application that the 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);
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);
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 the following:
mm_log(string,ERROR);It should then return. No newline is included in the string, so this function has to output its own.