[Evolution-hackers] New ECollectionBackend methods

[Matthew Barnes <mbarnes redhat com>]

I finally have the basic framework in place for creating and deleting
folders on a remote server, with a working reference implementation in
Evolution-EWS.

The new APIs are documented here:
http://mbarnes.fedorapeople.org/account-mgmt/docs/

I'll just give a brief overview.

D-Bus Interfaces
================

The core of the framework is two new optional D-Bus interfaces for data
sources, similar to the existing "Removable" and "Writable" interfaces:

  org.gnome.evolution.dataserver.Source.RemoteCreatable

    Create() - creates a remote resource

  org.gnome.evolution.dataserver.Source.RemoteDeletable

    Delete() - deletes a remote resource

The ESource class now has two new read-only boolean properties,
"remote-creatable" and "remote-deletable", to indicate whether the
ESource supports these capabilities.

The EServerSideSource class, which is like a "super" ESource in the
registry service, inherits these properties and makes then read/write.
Setting either property to TRUE from within the registry service exports
the interface over D-Bus, FALSE withdraws the interface.

Client-Side Methods
===================

On the client-side, the methods for these new interfaces are invoked
directly through ESource.  Both synchronous and asynchronous versions
exist; the synchronous APIs look like this:

  gboolean  e_source_remote_create_sync  (ESource *source,
                                          ESource *scratch_source,
                                          GCancellable *cancellable,
                                          GError **error);

  gboolean  e_source_remote_delete_sync  (ESource *source,
                                          GCancellable *cancellable,
                                          GError **error);

The corresponding boolean property must be TRUE or the method call will
fail with a NOT_SUPPORTED error.  Also the "scratch_source" argument is
a description of the new resource to create.  Typically a scratch source
is assembled by a configuration editor like ESourceConfig.

Note: I use the term "scratch source" throughout the API.  This is meant
to be analogous to scratch paper, or something temporary and disposable.
Specifically it means the ESource has no internal GDBusObject linking it
to any data source exported by the registry server.

Server-Side Methods
===================

On the server-side, EServerSideSource receives method invocations from
clients and forwards them to an ECollectionBackend instance to actually
do the remote creation and deletion.

ECollectionBackendClass has some new synchronous and asynchronous
virtual methods.  This is done in the same style as Camel, where by
default the asynchronous method calls the synchronous method from a
thread, so subclasses need only implement the synchronous method.

The synchronous virtual methods are:

  gboolean  (*create_resource_sync)  (ECollectionBackend *backend,
                                      ESource *source,
                                      GCancellable *cancellable,
                                      GError **error);

  gboolean  (*delete_resource_sync)  (ECollectionBackend *backend,
                                      ESource *source,
                                      GCancellable *cancellable,
                                      GError **error);

Collection backends implementing these methods are expected to perform
the remote operation first, and if successful then add/remove the data
source to/from the ESourceRegistryServer.  E-D-S clients will then see
the data source appear or disappear.

Policies
========

Neither of these new interfaces are exported by default in the registry
service, at least for now.  Each collection backend has to export them
explicitly if they wish to support the feature.  Technically speaking,
the interfaces can be exported on any data source, but the expectation
is:

  - The data source representing the collection itself will export the
    "RemoteCreatable" interface.

  - Data sources created by the collection backend to proxy a resource
    on a groupware server will export the "RemoteDeletable" interface.


With Evolution-EWS working, I'll be moving on to help Christian again
with Evolution-Kolab next week.  I assume Milan will handle Evo-MAPI.
If there's time before 3.6, I think it would be cool to also support
this in the Google and Yahoo! backends along with auto-discovery.

Questions or comments, you know where to find me.

Matthew Barnes