Libmailcheck- take two

[rms39 columbia edu (Russell Steinthal)]

Hmm... We didn't quite build a first version and throw it away, but 
we came fairly close.  :)

Seriously, thanks for the suggestions.  Yes, obviously a notification 
system is much better than one which requires active polling, 
especially when we're dealing with networks (and yes, I did envision 
abstracting POP3 or IMAP mailboxes along with mbox and MH folders, 
among others).

So here's another attempt, borrowing heavily from people's 
suggestions:

There are three main interfaces: set creation/deletion, mailbox 
registration, and notification.  The first two would, as Havoc 
pointed out, probably only be used by the control center or some sort 
of dot-file interface.  (But I can see a complex app like Balsa 
potentially interacting directly at this level as well.)  The third 
would be used by most front-ends to register which sets they would 
like to be notified for.

At least one person was confused by what I meant by a set, so let me 
try another explanation.  Basically, I'd envision that different 
applications might want to monitor different sets of mailboxes.  For 
example, I might put two mailcheck applets on my panel, one 
configured to use an audio alarm, and the other silent.  I would set 
the audible one to alert me to new mail in my personal inbox folder 
or gnome-announce, for example, while telling the silent one to 
monitor mail to gnome-devel and gnome-list, which I don't want to be 
disturbed with by frequent alarms.  (Actually, even better would be 
an enhanced mailcheck applet which could do both, but know to sound 
an audible alarm for certain categories, etc).  In the code below, 
MailboxSet can be assumed to be a typedef for an integer- it's just 
used to uniquely identify a set,

So, the set creation/deletion interface would look like:

MailboxSet gnome_mailcheck_create_set(void);
void       gnome_mailcheck_delete_set(MailboxSet set);

(Those could potentially be changed to included named sets, but I'm 
not sure if I think that should be a higher level abstraction or 
included in the actual library.)

The mailbox registration interface would be used by the control 
center to add or delete specific mailboxes from sets.  To answer 
several people's questions, yes, I would envision including 
POP3/IMAP/other mailbox formats in the library, and they would each 
have their own registration function, which could potentially accept 
whatever parameters they needed (hostname, username, password, etc).  
(The suggestion to use fetchmail is intriguing, since it would remove 
a good deal of code from the library which is already written better 
than I could hope to.  But do we want to rely on it from inside of 
gnome-libs?  I don't know enough about the architecture of the rest 
of the GNOME libraries to know if that's a problem...)

gboolean gnome_mailcheck_register_mbox(gchar* fname, MailboxSet set);
gboolean gnome_mailcheck_register_mhfolder(gchar* pathname, 
MailboxSet set);
gboolean gnome_mailcheck_register_pop3(gchar* host, gchar* user, 
gchar* pass);

We can include as many other mailbox types as people can come up 
with, just imagine similar functions.  There would also be 
corresponding unregister_* functions to remove them from sets, of 
course (omitted to save space in what is already a long message).

Finally, there's the notification interface, which is the only one 
which most applications would deal with:

typedef struct
{
     gchar* mailbox_name;
     int total_messages;
     int new_messages;
     struct MailInfo* next;
} MailInfo;

gboolean gnome_mailcheck_register_checker(void (*notify)(MailInfo* 
mboxes),
                                          MailboxSet set);

We'd probably want an unregister function as well, but I don't know 
how that's usually handled- should we return a unique identifier from 
register_checker()?

Note that I don't know much about how the GTK+ signal system works, 
so I wrote a generic function pointer version; that can obviously be 
changed to whatever form is natural for GTK programmers.

Internally, there would be a gnome_mailcheck_internal_check_*() 
routine for each of the mailbox types which would do the actual 
checking when needed.  Perhaps we'd need a function like 
gnome_mailcheck_set_check_interval(int seconds) in the configuration 
interface to configure that?  Even better, I think, would be if that 
were an argument to create_set() so that one could check local 
mbox/MH folders more frequently than remote POP3 mailboxes, for 
example.

Several general notes before I close:

* Most of my recent coding has been in C++, so if my C looks wrong in 
areas like typedef'ing structs or using booleans, my apologies.  gcc 
is quite efficient at pointing those sorts of errors out to me, 
however, so they get fixed quite quickly. :)

* Almost everywhere where I used a MailboxSet above, it might be 
useful to use a list of MailboxSet's instead.  It's a tradeoff 
between having multiple calls to the functions versus dealing with 
linked lists...

* I only mentioned mbox, MH, POP3, and IMAP mailboxes because that's 
what I've used.  Obviously we can include as many other mailbox types 
as people think of.

* I've ignored authentication issues, other than implying that we 
could pass as many arguments as needed to the register_pop3 function, 
etc.  Havoc seemed to imply that CORBA could be useful here, but I'm 
really unclear on this...

Once again, comments are appreciated.  There are probably going to 
several more rounds of this before I even start coding, which is 
better than my coding (or copying other's code) and then discovering 
the design is flawed, so get ready, get set, FIRE AWAY!

-Russell
-- 
Russell Steinthal
<rms39@columbia.edu>		Columbia College Class of 1999
<steintr@avnet.org>		System Administrator, AV-Network