Final (?) design for libmailcheck- comments appreciated

[rms39 columbia edu (Russell Steinthal)]

Sorry to bombard the list with yet another design sketch for
libmailcheck, but I've finalized my ideas for the interfaces and am
starting to implement an initial version of the code; I wanted to post
the interfaces one last time to see if anyone has any other comments
before I get too far into implementation.

First, on the CORBA side, I have the following two interfaces:

module GNOME
{
  interface MailCheckClient
    {
      void notify(in string mailbox);
      void new_mailbox(in string mailbox);
      void delete_mailbox(in string mailbox);
      void server_shutdown();
    };

  interface MailCheckServer
    {
      typedef sequence<string> stringList;
      stringList    mailbox_types();
      stringList    list_mailboxes();
      boolean       register_client(in MailCheckClient client);
      void          set_monitor_status(in MailCheckClient client, 
				       in string name,
				       in boolean status);
      boolean       get_monitor_status(in MailCheckClient client,
				       in string name);
      boolean       create_mailbox(in string type, in string name);

      boolean       destroy_mailbox(in string name);
      void          set_check_interval(in string name, 
				       in unsigned long secs);
      unsigned long get_check_interval(in string name);
      boolean       authenticate_mailbox(in string name, 
					 in string password);
    };
};

Those will be mapped onto two new GTK widgets: GNOMEMailChecker will
emit three signals: new_mailbox, delete_mailbox, and shutdown; and
GNOMEMailbox will emit the signals: new_mail, mailbox_undefined, and
authenticate (see below).

I believe it will be possible to totally insulate clients from the
CORBA server using the following function interface:

/* initialization/termination functions */
GNOMEMailChecker* gnome_mailcheck_init(void);
GNOMEMailChecker* gnome_mailcheck_init_with_auth_func(GNOMEAuthFunc 
func);
gboolean          gnome_mailcheck_quit(void);

/* client interface */
GList*            gnome_mailcheck_list_mailboxes(void);
GList*            gnome_mailcheck_list_mailbox_types(void);

/* configuration interface (probably only used by gnomecc) */
gboolean          gnome_mailcheck_define_mailbox(gchar* type, gchar* 
name);
gboolean          gnome_mailcheck_undefine_mailbox(gchar* name);

gint              gnome_mailcheck_get_check_interval(gchar* name);
gboolean          gnome_mailcheck_set_check_interval(gchar* name, int 
secs);

/* helper functions */

gboolean          gnome_mailcheck_authenticate_mailbox(GNOMEMailbox* 
box);

The semantics should be fairly self-explanatory, but if you have any
questions, feel free to ask.  There will obviously be additional
functions in the widgets (most likely) to handle the actual client
CORBA interface.

Some random notes:

* To monitor a mailbox, a client would first call
  gnome_mailcheck_init(), then gnome_mailcheck_list_mailboxes(), and
  finally would instantiate a new GNOMEMailbox object using
  gnome_mailbox_new(gchar* name).  It could then attach signal
  handlers as required.

* When the CORBA server needs an authentication token (i.e. a
  password) for a mailbox, it will cause the first registered client
  to emit the authenticate signal.  All clients, therefore, must
  specify a handler for that signal (in most cases, this will probably
  be gnome_mailcheck_authenticate_mailbox()).  The handler must then
  call authenticate_mailbox() on the CORBA server with the password.

* I expect gnome_mailcheck_authenticate_mailbox to build a prompt
  string and pass it to a generic password dialog box (to be written);
  it will then call authenticate_mailbox() as required.

* Actual mailbox types (mbox, MH, POP3, etc.) will be new widgets	
  derived from GNOMEMailbox, along with an internal function for the
  CORBA server (the precise interface still to be defined).  The GTK
  widget should allow properties pages to be dynamically built by
  gtk-args, and the internal function will be used to actually poll
  the mailbox for new mail.

* The two external helper functions which this design will rely upon
  (at least) are the generic password dialog box (which I assume will
  take a prompt string and return a password string) and the
  property-box-from-gtk-args function.  The latter is obviously more
  complex, but libmailcheck's configuration interface basically
  requires it (or at least a specialized version of it).  Is anyone
  (Ian?) interested in working on that in parallel to my work on the
  mailcheck code itself?

* The {set,get}_monitor_status calls in the server CORBA interface are
  a bit sketchy at this point; I'm planning on having the
  gnome_mailbox_new function call them to set a status flag, so that
  the CORBA server has some idea which mailboxes are being monitored
  by which servers.  That's really only needed as an optimization,
  however (I think), since we can always call notify() on each
  registered client even if it is not monitoring the given mailbox (it
  will simply be ignored by the client).

If anyone has any further comments on the interfaces or design, this
is the best time to raise them, as I'm getting into the implementation
at this point.  At this point, I'm planning on writing a first pass of
the implementation on my own, but if anyone wants to help, let me
know.  Once that's done, I'll worry about writing backends/widgets for
various mailbox types.  (I'll probably try to do MBOX as a
proof-of-concept...)  Hopefully, other people will contribute code for
mailbox backends, but I know I need to have some working code for them
to work with first.

Anyway, comments are greatly appreciated, especially since I'm neither
a CORBA nor a GTK expert.  I've read through the control-center code,
which is my primary model for the CORBA interface, but that's really
not enough- there's still a good deal of trial and error ahead of
me.:)

Finally, I don't have CVS write access, so my initial coding is on my
local machine.  If anyone wants the full header files/implementations
I have so far, e-mail me and I'll either send them to you or make them
available on my web server.  (Or someone can tell me what to do to get
the code into CVS; otherwise, I'll wait until I had a reasonably
working first version before worrying about that.)

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