this documentation is out of date, but still applies somewhat.

----

(May 1998)
Okay, let's try to document Balsa's mailbox abstraction for
the libmutt library.


Opening and Closing a Mailbox
-----------------------------
Mailboxes are not directly opened and closed, instead the open
state of the mailbox is reference-counted.  When you want to start
using a mailbox, use:

mailbox_open_ref (mailbox);

when you are done with it:

mailbox_open_unref (mailbox);



Mailbox Watchers
----------------
The GUI components in Balsa need a way of knowing when a mailbox
has a state change.  This is accomplished by "mailbox watchers".

This is the current list of messages a mailbox watcher can
recieve:

typedef enum
{
  MESSAGE_MARK_READ,        /* message has changed from new to read */
  MESSAGE_MARK_DELETE,      /* message has been marked deleted */
  MESSAGE_MARK_UNDELETE,    /* message has been marked undeleted */
  MESSAGE_DELETE,           /* message has been deleted */
  MESSAGE_NEW,              /* message is new to the mailbox */
} MailboxWatcherMessageType;


A mailbox watcher is set by:

guint 
mailbox_watcher_set (Mailbox * mailbox, 
		     MailboxWatcherFunc func,
		     guint16 mask,
		     gpointer data);

this returns the watcher ID, which is used to identify the
watcher in other mailbox_watcher_* calls:

mailbox_watcher_remove (mailbox, guint id);
mailbox_watcher_remove_by_data (mailbox, gpointer data);

will remove the watcher.  The message reciever is a MailboxWatcherFunc.
Its form is:

typedef void (*MailboxWatcherFunc) (MailboxWatcherMessage *);