ECollectionBackend

## 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.