ECollectionBackend

ECollectionBackend — A base class for a data source collection backend

Synopsis

#include <libebackend/libebackend.h>

struct              ECollectionBackend;
ESource *           e_collection_backend_new_child      (ECollectionBackend *backend,
                                                         const gchar *resource_id);
struct _ESourceRegistryServer * e_collection_backend_ref_server
                                                        (ECollectionBackend *backend);
const gchar *       e_collection_backend_get_cache_dir  (ECollectionBackend *backend);
gchar *             e_collection_backend_dup_resource_id
                                                        (ECollectionBackend *backend,
                                                         ESource *child_source);
GList *             e_collection_backend_claim_all_resources
                                                        (ECollectionBackend *backend);
GList *             e_collection_backend_list_calendar_sources
                                                        (ECollectionBackend *backend);
GList *             e_collection_backend_list_contacts_sources
                                                        (ECollectionBackend *backend);
GList *             e_collection_backend_list_mail_sources
                                                        (ECollectionBackend *backend);
gboolean            e_collection_backend_create_resource_sync
                                                        (ECollectionBackend *backend,
                                                         ESource *source,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_collection_backend_create_resource
                                                        (ECollectionBackend *backend,
                                                         ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_collection_backend_create_resource_finish
                                                        (ECollectionBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_collection_backend_delete_resource_sync
                                                        (ECollectionBackend *backend,
                                                         ESource *source,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_collection_backend_delete_resource
                                                        (ECollectionBackend *backend,
                                                         ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_collection_backend_delete_resource_finish
                                                        (ECollectionBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Object Hierarchy

  GObject
   +----EBackend
         +----ECollectionBackend

Properties

  "server"                   ESourceRegistryServer*  : Read / Write / Construct Only

Signals

  "child-added"                                    : Run Last
  "child-removed"                                  : Run Last

Description

ECollectionBackend is a base class for backends which manage a collection of data sources that collectively represent the resources on a remote server. The resources can include any number of private and shared email stores, calendars and address books.

The backend's job is to synchronize local representations of remote resources by adding and removing EServerSideSource instances in an ESourceRegistryServer. If possible the backend should also listen for notifications of newly-added or deleted resources on the remote server or else poll the remote server at regular intervals and then update the data source collection accordingly.

As most remote servers require authentication, the backend may also wish to implement the ESourceAuthenticator interface so it can submit its own EAuthenticationSession instances to the ESourceRegistryServer.

Details

struct ECollectionBackend

struct ECollectionBackend;

Contains only private data that should be read and manipulated using the functions below.

Since 3.6


e_collection_backend_new_child ()

ESource *           e_collection_backend_new_child      (ECollectionBackend *backend,
                                                         const gchar *resource_id);

Creates a new EServerSideSource as a child of the collection "source" owned by backend. If possible, the EServerSideSource is drawn from a cache of previously used sources indexed by resource_id so that locally cached data from previous sessions can be reused.

The returned data source should be passed to e_source_registry_server_add_source() to export it over D-Bus.

Return: a newly-created data source

backend :

an ECollectionBackend

resource_id :

a stable and unique resource ID

Since 3.6


e_collection_backend_ref_server ()

struct _ESourceRegistryServer * e_collection_backend_ref_server
                                                        (ECollectionBackend *backend);

Returns the ESourceRegistryServer to which backend belongs.

The returned ESourceRegistryServer is referenced for thread-safety. Unreference the ESourceRegistryServer with g_object_unref() when finished with it.

backend :

an ECollectionBackend

Returns :

the ESourceRegisterServer for backend

Since 3.6


e_collection_backend_get_cache_dir ()

const gchar *       e_collection_backend_get_cache_dir  (ECollectionBackend *backend);

Returns the private cache directory path for backend, which is named after the "uid" of backend's collection "source".

The cache directory is meant to store key files for backend-created data sources. See also: e_server_side_source_set_write_directory()

backend :

an ECollectionBackend

Returns :

the cache directory for backend

Since 3.6


e_collection_backend_dup_resource_id ()

gchar *             e_collection_backend_dup_resource_id
                                                        (ECollectionBackend *backend,
                                                         ESource *child_source);

Extracts the resource ID for child_source, which is supposed to be a stable and unique server-assigned identifier for the remote resource described by child_source. If child_source is not actually a child of the collection "source" owned by backend, the function returns NULL.

The returned string should be freed with g_free() when no longer needed.

backend :

an ECollectionBackend

child_source :

an ESource managed by backend

Returns :

a newly-allocated resource ID for child_source, or NULL

Since 3.6


e_collection_backend_claim_all_resources ()

GList *             e_collection_backend_claim_all_resources
                                                        (ECollectionBackend *backend);

Claims all previously used sources that have not yet been claimed by e_collection_backend_new_child() and returns them in a GList. Note that previously used sources can only be claimed once, so subsequent calls to this function for backend will return NULL.

The backend is then expected to compare the returned list with a current list of resources from a remote server, create new ESource instances as needed with e_collection_backend_new_child(), discard unneeded ESource instances with e_source_remove(), and export the remaining instances with e_source_registry_server_add_source().

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned GList itself with g_list_free().

An easy way to free the list properly in one step is as follows:

1
g_list_free_full (list, g_object_unref);

backend :

an ECollectionBackend

Returns :

a list of previously used sources

Since 3.6


e_collection_backend_list_calendar_sources ()

GList *             e_collection_backend_list_calendar_sources
                                                        (ECollectionBackend *backend);

Returns a list of calendar sources belonging to the data source collection managed by backend.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned GList itself with g_list_free().

An easy way to free the list properly in one step is as follows:

1
g_list_free_full (list, g_object_unref);

backend :

an ECollectionBackend

Returns :

a list of calendar sources

Since 3.6


e_collection_backend_list_contacts_sources ()

GList *             e_collection_backend_list_contacts_sources
                                                        (ECollectionBackend *backend);

Returns a list of address book sources belonging to the data source collection managed by backend.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned GList itself with g_list_free().

An easy way to free the list properly in one step is as follows:

1
g_list_free_full (list, g_object_unref);

backend :

an ECollectionBackend

Returns :

a list of address book sources

Since 3.6


e_collection_backend_list_mail_sources ()

GList *             e_collection_backend_list_mail_sources
                                                        (ECollectionBackend *backend);

Returns a list of mail sources belonging to the data source collection managed by backend.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned GList itself with g_list_free().

An easy way to free the list properly in one step is as follows:

1
g_list_free_full (list, g_object_unref);

backend :

an ECollectionBackend

Returns :

a list of mail sources

Since 3.6


e_collection_backend_create_resource_sync ()

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

Creates a server-side resource described by source. For example, if source describes a new calendar, an equivalent calendar is created on the server.

It is the implementor's responsibility to examine source and determine what the equivalent server-side resource would be. If this cannot be determined without ambiguity, the function must return an error.

After the server-side resource is successfully created, the implementor must also add an ESource to backend's "server". This can either be done immediately or in response to some "resource created" notification from the server. The added ESource can be source itself or a different ESource instance that describes the new resource.

If an error occurs, the function will set error and return FALSE.

backend :

an ECollectionBackend

source :

an ESource

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.6


e_collection_backend_create_resource ()

void                e_collection_backend_create_resource
                                                        (ECollectionBackend *backend,
                                                         ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously creates a server-side resource described by source. For example, if source describes a new calendar, an equivalent calendar is created on the server.

It is the implementor's responsibility to examine source and determine what the equivalent server-side resource would be. If this cannot be determined without ambiguity, the function must return an error.

After the server-side resource is successfully created, the implementor must also add an ESource to backend's "server". This can either be done immediately or in response to some "resource created" notification from the server. The added ESource can be source itself or a different ESource instance that describes the new resource.

When the operation is finished, callback will be called. You can then call e_collection_backend_create_resource_finish() to get the result of the operation.

backend :

an ECollectionBackend

source :

an ESource

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.6


e_collection_backend_create_resource_finish ()

gboolean            e_collection_backend_create_resource_finish
                                                        (ECollectionBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_collection_backend_create_resource().

If an error occurred, the function will set error and return FALSE.

backend :

an ECollectionBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.6


e_collection_backend_delete_resource_sync ()

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

Deletes a server-side resource described by source. The source must be a child of backend's collection "source".

After the server-side resource is successfully deleted, the implementor must also remove source from the backend's "server". This can either be done immediately or in response to some "resource deleted" notification from the server.

If an error occurs, the function will set error and return FALSE.

backend :

an ECollectionBackend

source :

an ESource

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.6


e_collection_backend_delete_resource ()

void                e_collection_backend_delete_resource
                                                        (ECollectionBackend *backend,
                                                         ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously deletes a server-side resource described by source. The source must be a child of backend's collection "source".

After the server-side resource is successfully deleted, the implementor must also remove source from the backend's "server". This can either be done immediately or in response to some "resource deleted" notification from the server.

When the operation is finished, callback will be called. You can then call e_collection_backend_delete_resource_finish() to get the result of the operation.

backend :

an ECollectionBackend

source :

an ESource

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.6


e_collection_backend_delete_resource_finish ()

gboolean            e_collection_backend_delete_resource_finish
                                                        (ECollectionBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_collection_backend_delete_resource().

If an error occurred, the function will set error and return FALSE.

backend :

an ECollectionBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.6

Property Details

The "server" property

  "server"                   ESourceRegistryServer*  : Read / Write / Construct Only

The server to which the backend belongs.

Signal Details

The "child-added" signal

void                user_function                      (ECollectionBackend *backend,
                                                        EServerSideSource  *child_source,
                                                        gpointer            user_data)         : Run Last

Emitted when an EServerSideSource is added to backend's "server" as a child of backend's collection "source".

You can think of this as a filtered version of ESourceRegistryServer's "source-added" signal which only lets through sources relevant to backend.

backend :

the ECollectionBackend which emitted the signal

child_source :

the newly-added child EServerSideSource

user_data :

user data set when the signal handler was connected.

The "child-removed" signal

void                user_function                      (ECollectionBackend *backend,
                                                        EServerSideSource  *child_source,
                                                        gpointer            user_data)         : Run Last

Emitted when an EServerSideSource that is a child of backend's collection "source" is removed from backend's "server".

You can think of this as a filtered version of ESourceRegistryServer's "source-removed" signal which only lets through sources relevant to backend.

backend :

the ECollectionBackend which emitted the signal

child_source :

the child EServerSideSource that got removed

user_data :

user data set when the signal handler was connected.