ECollectionBackend: Evolution-Data-Server Reference Manual

## ECollectionBackend ECollectionBackend — A base class for a data source collection backend |

## Functions

ESource * | e_collection_backend_new_child ()
gboolean | e_collection_backend_is_new_source ()
GProxyResolver * | e_collection_backend_ref_proxy_resolver ()
struct _ESourceRegistryServer * | e_collection_backend_ref_server ()
const gchar * | e_collection_backend_get_cache_dir ()
gchar * | e_collection_backend_dup_resource_id ()
GList * | e_collection_backend_claim_all_resources ()
GList * | e_collection_backend_list_calendar_sources ()
GList * | e_collection_backend_list_contacts_sources ()
GList * | e_collection_backend_list_mail_sources ()
gboolean | e_collection_backend_create_resource_sync ()
void | e_collection_backend_create_resource ()
gboolean | e_collection_backend_create_resource_finish ()
gboolean | e_collection_backend_delete_resource_sync ()
void | e_collection_backend_delete_resource ()
gboolean | e_collection_backend_delete_resource_finish ()
void | e_collection_backend_authenticate_children ()
void | e_collection_backend_schedule_populate ()
gboolean | e_collection_backend_get_populate_frozen ()
gboolean | e_collection_backend_freeze_populate ()
void | e_collection_backend_thaw_populate ()
gboolean | e_collection_backend_get_part_enabled ()

## Types and Values

struct | ECollectionBackend

## Object Hierarchy

        GObject
        ╰── EBackend
            ╰── ECollectionBackend
                ╰── EWebDAVCollectionBackend

## Includes

    #include <libebackend/libebackend.h>

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

The client is responsible to provide credentials to use to authenticate.

## Functions

### 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: (transfer full): a newly-created data source

#### Parameters

backend | an ECollectionBackend |
resource_id | a stable and unique resource ID |

Since: 3.6

### e_collection_backend_is_new_source ()

    gboolean
    e_collection_backend_is_new_source (ECollectionBackend *backend,
                                        ESource *source);

Returns whether the `source` is a newly created child or not. New sources are remembered between two populate calls only.

#### Parameters

backend | an ECollectionBackend |
source | a child ESource |

#### Returns

`TRUE`, when the `source` is a new child; `FALSE` when it had been known before.

Since: 3.32

### e_collection_backend_ref_proxy_resolver ()

    GProxyResolver *
    e_collection_backend_ref_proxy_resolver
                                   (ECollectionBackend *backend);

Returns the GProxyResolver for `backend` (if applicable), as indicated by the “proxy-uid” of `backend` 's “source” or one of its ancestors.

The returned GProxyResolver is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

backend | an ECollectionBackend |

#### Returns

a GProxyResolver, or `NULL`.

[transfer full][nullable]

Since: 3.12

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

#### Parameters

backend | an ECollectionBackend |

#### Returns

the ESourceRegistryServer for `backend` .

[transfer full][type ESourceRegistryServer]

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()`

#### Parameters

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.

#### Parameters

backend | an ECollectionBackend |
child_source | an ESource managed by `backend` |

#### Returns

a newly-allocated resource ID for `child_source` , or `NULL`.

[nullable]

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);

#### Parameters

backend | an ECollectionBackend |

#### Returns

a list of previously used sources.

[element-type ESource][transfer full][nullable]

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);

#### Parameters

backend | an ECollectionBackend |

#### Returns

a list of calendar sources.

[element-type ESource][transfer full]

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);

#### Parameters

backend | an ECollectionBackend |

#### Returns

a list of address book sources.

[element-type ESource][transfer full]

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);

#### Parameters

backend | an ECollectionBackend |

#### Returns

a list of mail sources.

[element-type ESource][transfer full]

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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_authenticate_children ()

    void
    e_collection_backend_authenticate_children
                                   (ECollectionBackend *backend,
                                    const ENamedParameters *credentials);

Authenticates all enabled children sources with the given `crendetials` . This is usually called when the collection source successfully used the `credentials` to connect to the (possibly) remote data store, to open the childern too. Already connected child sources are skipped.

#### Parameters

backend | an ECollectionBackend |
credentials | credentials to authenticate with |

Since: 3.16

### e_collection_backend_schedule_populate ()

    void
    e_collection_backend_schedule_populate
                                   (ECollectionBackend *backend);

Schedules a call to `populate()` of the `backend` on idle. The function does nothing in case the `backend` is offline.

#### Parameters

backend | an ECollectionBackend |

Since: 3.30

### e_collection_backend_get_populate_frozen ()

    gboolean
    e_collection_backend_get_populate_frozen
                                   (ECollectionBackend *backend);

#### Parameters

backend | an ECollectionBackend |

#### Returns

Whether the backend has currently frozen (disabled) populate of its content.

Since: 3.38

### e_collection_backend_freeze_populate ()

    gboolean
    e_collection_backend_freeze_populate (ECollectionBackend *backend);

Freezes populate of the backend's content. This is used to avoid calling populate multiple times in parallel. Every call to this function should be followed by the call of `e_collection_backend_thaw_populate()` to reverse the effect of this function, regardless of the return value of this function.

#### Parameters

backend | an ECollectionBackend |

#### Returns

`TRUE`, when this is the first freeze call

Since: 3.38

### e_collection_backend_thaw_populate ()

    void
    e_collection_backend_thaw_populate (ECollectionBackend *backend);

Thaws populate of the backend's content. This is a pair function for `e_collection_backend_freeze_populate()`.

#### Parameters

backend | an ECollectionBackend |

Since: 3.38

### e_collection_backend_get_part_enabled ()

    gboolean
    e_collection_backend_get_part_enabled (ECollectionBackend *backend,
                                           ECollectionBackendParts parts);

Checks whether the `backend` has enabled at least of the `parts` .

#### Parameters

backend | an ECollectionBackend |
parts | a bit-or of ECollectionBackendParts with parts to be checked |

#### Returns

`TRUE`, when at least one of the `parts` is enabled and the backend's ESource is enabled as well.

Since: 3.40

## Types and Values

### struct ECollectionBackend

    struct ECollectionBackend;

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

Since: 3.6