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

## Functions

ESource * | e_collection_backend_new_child ()
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 ()

## Types and Values

struct | ECollectionBackend
struct | ECollectionBackendClass

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

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.

## 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: a newly-created data source

#### Parameters

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

Since 3.6

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

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

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

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

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

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

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

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

## Types and Values

### struct ECollectionBackend

    struct ECollectionBackend {
    	EBackend parent;
    	ECollectionBackendPrivate *priv;
    };

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

Since 3.6

### struct ECollectionBackendClass

    struct ECollectionBackendClass {
    	EBackendClass parent_class;

    	/* Methods */
    	void		(*populate)		(ECollectionBackend *backend);
    	gchar *		(*dup_resource_id) (ECollectionBackend *backend,
    						 ESource *child_source);

    	/* Signals */
    	void		(*child_added)		(ECollectionBackend *backend,
    						 ESource *child_source);
    	void		(*child_removed) (ECollectionBackend *backend,
    						 ESource *child_source);

    	/* More Methods (grouped separately to preserve the ABI) */
    	gboolean (*create_resource_sync) (ECollectionBackend *backend,
    						 ESource *source,
    						 GCancellable *cancellable,
    						 GError **error);
    	void		(*create_resource) (ECollectionBackend *backend,
    						 ESource *source,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*create_resource_finish)
    						(ECollectionBackend *backend,
    						 GAsyncResult *result,
    						 GError **error);
    	gboolean (*delete_resource_sync) (ECollectionBackend *backend,
    						 ESource *source,
    						 GCancellable *cancellable,
    						 GError **error);
    	void		(*delete_resource) (ECollectionBackend *backend,
    						 ESource *source,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*delete_resource_finish)
    						(ECollectionBackend *backend,
    						 GAsyncResult *result,
    						 GError **error);

    	gpointer reserved[10];
    };