Re: [Evolution-hackers] (summarize ][) New 'eclient' branch in eds

[Milan Crha <mcrha redhat com>]

On Mon, 2011-05-09 at 17:00 +0200, Milan Crha wrote:
> On Wed, 2011-05-04 at 14:37 +0200, Milan Crha wrote:
> > So here left basically three things,
> >    a) merging some API in utils, 

	Hi,
I committed a change, introducing libedataserverui/e-client-utils.h/.c

It adds new
   typedef enum {
	E_CLIENT_SOURCE_TYPE_CONTACTS,
	E_CLIENT_SOURCE_TYPE_EVENTS,
	E_CLIENT_SOURCE_TYPE_MEMOS,
	E_CLIENT_SOURCE_TYPE_TASKS
   } EClientSourceType;

(I chose this wording, in a sense: EClientSourceType tells you what is
stored behind the ESource. I harmonized this wording with
ECalClientSourceType too.)

The newly added functions are:
	e_client_utils_new
	e_client_utils_new_from_uri
	e_client_utils_new_system
	e_client_utils_new_default
	e_client_utils_set_default
	e_client_utils_set_default_source
	e_client_utils_get_sources

------------------------------------------------------------------------

The e_client_utils_open_new/_finish is still waiting its addition. Main
reason is that there is no mechanism, at the moment, to distinguish
current backend open mode/state. Right now it can be online and loaded.
It's not much documented, but from its usage I see that:
   online - TRUE, if the backend storage/server is reachable; use to be
            set in 'open' backend's method or unset on failed
            authentication or similar occasions
   loaded - TRUE, if the 'open' backend's method was called

What I would need is a signal from the backend, "fully-opened", which
may cover authentication too. (The "fully" prefix is rather redundant,
but self explanatory.)

When you look how the async open method for an addressbook is written,
that located in libedataserverui/e-book-auth-util.c, then after usual
"open" call on the EBook it checks whether the associated ESource has
"auth" set, and if so, then it *forces* the "authenticate_user" method
call. I believe it's not correct, it may wait and respond on backend's
authentication request, but because it's not clear in what state the
backend is, with respect of opening and authenticating, then I
understand there was not many options.

This is the interstate issue Matthew mentioned earlier, in another
thread, (I understand it that way at least), where is hard to
differentiate between open-called, authenticating, fully-opened/ready
for queries.

I propose following changes in the backend:
a) add 'opening' boolean flag, which will be managed automatically. It
will be set during 'open' call, and unset only if the storage/server
will be fully connected, thus if the server will require authentication,
then the backend asks for credentials and keeps this flag to TRUE. The
flag will be automatically unset also for cases when the 'open' method
call finishes with an error. During the opening phase every call to the
backend will deny with Busy error, except of close / cancel /
authenticate_user and similar calls.
b) the backend descendants will notify client about "opened" either
within 'open' call itself, for cases where notification is not needed,
or when it successfully connects to the storage/server (including
authentication), by a call to function like
e_book/cal_backend_notify_opened (backend, const GError *error);
The NULL error is meant for 'success'. This will invoke signal on the
client side with a result. The internal 'opening' flag will be updated
accordingly on the e_..._backend_notify_opened() call, which is supposed
to be called every time.
c) it may not matter if the e_..._backend_notify_opened() will be called
before or after the notification about 'open' method call.
d) a new backend property "opening" will be introduced.
e) the "loaded" property might be replaced with "opened" and will be set
to TRUE only after the backend is successfully opened and authenticated
against its storage/server (basically on e_..._backend_notify_opened()
call with error set to NULL).
f) setting 'online' to FALSE will not result in an opened=FALSE if it
was previously opened, though the backend descendant will be able to
unset the 'opened' flag, by calling the e_..._backend_notify_opened()
with the GError set to a detailed reason why it is not opened.
g) On the client side the EClient::open-changed signal will be
introduced, which will have one argument, the GError from the
e_..._backend_notify_opened(), which will be called on each invocation
from the backend itself.

It'll be easy to do an e_client_utils_open_new() properly with above
changes done, but I would like to know opinions from others whether such
change makes sense and if you'll not see any issue with this approach.
If not, then I'll be more than happy to do this change in the EClient
branch.
	Bye,
	Milan