Another attempt at a libmailcheck design

[rms39 columbia edu (Russell Steinthal)]

Ok, now that I've sat on all the comments from the last go-around for 
a week or so, here's my next pass at a design.

I've divided the functionality into three categories: the CORBA 
interface, the libmailcheck interface, and support routines.  
Basically, I've assumed that all the implementation code will be in 
the CORBA server, libmailcheck will be used to hide the CORBA from 
the clients (linking with gnome-libs rather than orbit is likely to 
make clients' lives easier, at least I think it will), and the 
support routines are things which have potential usefulness outside 
of the mailchecker, so might be best extracted into some other 
library.

To briefly summarize, I think the best suggestion so far has been to 
use GTK+ objects for as much as possible.  Therefore, I'd envision a 
hierarchy looking something like this: GTKObject --> GNOMEMailbox --> 
GNOMEMailbox_MBOX, GNOME_Mailbox_IMAP, etc.  In all probability, only 
the control center will deal with the most-derived level of objects 
(to configure them); clients will see pointers to GNOMEMailbox's, 
which will emit appropriate signals (probably new_mail and some sort 
of termination signal if the user "undefines" it).  The control 
center can either use gtk-args to configure the mailbox, or can pass 
it to a utility function to build a properties page for it (see 
below).  (This assumes that gtk-args can do what Ian says it can, and 
that I (or someone else) can figure out how to use it...)

The only data member which GNOMEMailbox would have would be a name, 
which should be sufficient for clients to build lists of available 
mailboxes, etc.  (I'm assuming that the user would set the names in 
the control center appropriately, and that there's no need for the 
clients to know the configuration details; for example, I'd define a 
mailbox with the name "My POP account", but the client wouldn't care 
what the username/host was, etc.)

The final caveat before I launch into function interfaces, etc. is 
that my syntax probably needs some work: I'm assuming, for instance, 
that GTK+ inheritance works similar to C++, so I can safely return a 
pointer to one of the actual mailbox types from a function which is 
declared to return GNOMEMailbox* (I think that's consistent with code 
I've seen).  Similarly, my IDL specification is probably 
syntactically wrong, but I hope you can get the point... (And I don't 
know how GTK structures map into CORBA...)

The CORBA interface:
--------------------
interface GNOME::MailCheck
{
     sequence<string>         list_mailbox_types();
     sequence<GNOMEMailbox*>  list_mailboxes();
     GNOMEMailbox*            create_mailbox(string type, string 
name);
     boolean                  destroy_mailbox(string name);
     GNOMEMailbox*            get_handle(string name);
     void                     set_check_interval(string name, int 
interval);
     int                      get_check_interval(string name);
     void                     set_auth_func(string name, function* 
func);
}

Notes:

* I don't know if I think destroy_mailbox() and the set, get 
functions should take string names or actual pointers to objects.  (I 
think it's cleaner when we don't pass pointers out, but the clients 
need GTK+ objects...)

* The goal of set_auth_func() is for the client to specify a function 
which will be called when a password is needed for a given mailbox; 
the function would return the password to the CORBA server, which 
would then pass it on to the appropriate mailserver.

* This design obviously assumes some questionable things, namely that 
GTK+ object pointers and function pointers can be passed from/to the 
CORBA server.  I have a sinking feeling that breaks interoperability 
and so won't work...

The libmailcheck interface:
---------------------------
glist gnome_mailcheck_list_mailbox_types(void);
glist gnome_mailcheck_list_mailboxes();
GNOMEMailbox* gnome_mailcheck_define_mailbox(gchar* type, gchar* 
name, auth_func func);
gboolean gnome_mailcheck_undefine_mailbox(gchar* name);
GNOMEMailbox* gnome_mailcheck_get_mailbox_handle(gchar* name);

Notes: 

Basically, these just wrap the CORBA interface; if we decide that 
gnome_mailcheck_list_mailboxes returns a list of Mailbox*'s, rather 
than strings, then there's no real need for get_mailbox_handle.

Other support functions
-----------------------
* A function to build a properties dialog box for an object, using 
gtk-args; this would be used by gnomecc to configure a mailbox (which 
had been created using gnome_mailcheck_define_mailbox(), which 
returns a Mailbox*).

* A function which displays a dialog box to prompt the user for a 
password; clients could pass this as the third argument to 
define_mailbox() to handle authentication.

I think that about covers all the functionality we need...  If it's 
not clear enough, the clients would simply get a pointer to the 
mailbox they wanted (by its name, either by a function call or by 
scanning the entire list) and then attach callback functions to the 
new_mail signal.  The only thing which isn't covered by this scheme 
is if two clients want to use different check intervals on the same 
mailbox: since check interval is set per mailbox, this doesn't work.  
I don't see this as being such a problem, though... (The user could 
define two mailboxes with different check intervals pointing to the 
same source, but then we have locking issues...)

Anyway, comments are appreciated, especially if I totally mangled any 
GTK/CORBA concepts.  I *think* I incorporated almost all the 
suggestions people made earlier; I just hope I didn't include any 
contradictory ones. :)

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