ESourceRegistryServer

## ESourceRegistryServer ESourceRegistryServer — Server-side repository for data sources |

## Synopsis

    #include <libebackend/libebackend.h>

    #define             E_SOURCE_REGISTRY_SERVER_OBJECT_PATH
    #define             EDS_REGISTRY_MODULES
    struct              ESourceRegistryServer;
    EDBusServer *       e_source_registry_server_new        (void);
    void                e_source_registry_server_add_source (ESourceRegistryServer *server,
                                                             ESource *source);
    void                e_source_registry_server_remove_source
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);
    enum                ESourcePermissionFlags;
    gboolean            e_source_registry_server_load_directory
                                                            (ESourceRegistryServer *server,
                                                             const gchar *path,
                                                             ESourcePermissionFlags flags,
                                                             GError **error);
    gboolean            e_source_registry_server_load_resource
                                                            (ESourceRegistryServer *server,
                                                             GResource *resource,
                                                             const gchar *path,
                                                             ESourcePermissionFlags flags,
                                                             GError **error);
    ESource *           e_source_registry_server_load_file  (ESourceRegistryServer *server,
                                                             GFile *file,
                                                             ESourcePermissionFlags flags,
                                                             GError **error);
    void                e_source_registry_server_load_error (ESourceRegistryServer *server,
                                                             GFile *file,
                                                             const GError *error);
    ESource *           e_source_registry_server_ref_source (ESourceRegistryServer *server,
                                                             const gchar *uid);
    GList *             e_source_registry_server_list_sources
                                                            (ESourceRegistryServer *server,
                                                             const gchar *extension_name);
    ESource *           e_source_registry_server_find_extension
                                                            (ESourceRegistryServer *server,
                                                             ESource *source,
                                                             const gchar *extension_name);
    ECollectionBackend * e_source_registry_server_ref_backend
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);
    ECollectionBackendFactory * e_source_registry_server_ref_backend_factory
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);
    EAuthenticationSession * e_source_registry_server_new_auth_session
                                                            (ESourceRegistryServer *server,
                                                             ESourceAuthenticator *authenticator,
                                                             const gchar *source_uid);
    gboolean            e_source_registry_server_authenticate_sync
                                                            (ESourceRegistryServer *server,
                                                             EAuthenticationSession *session,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_registry_server_authenticate
                                                            (ESourceRegistryServer *server,
                                                             EAuthenticationSession *session,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_registry_server_authenticate_finish
                                                            (ESourceRegistryServer *server,
                                                             GAsyncResult *result,
                                                             GError **error);

    gboolean            e_source_registry_server_load_all   (ESourceRegistryServer *server,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----EDBusServer
             +----EDataFactory
                   +----ESourceRegistryServer

## Implemented Interfaces

ESourceRegistryServer implements EExtensible.

## Signals

      "files-loaded"                                   : Run Last
      "load-error"                                     : Run Last
      "source-added"                                   : Run Last
      "source-removed"                                 : Run Last
      "tweak-key-file"                                 : Run Last

## Description

The ESourceRegistryServer is the heart of the registry D-Bus service. Acting as a global singleton store for all EServerSideSource instances, its responsibilities include loading data source content from key files, exporting data sources to clients over D-Bus, handling authentication and content change requests from clients, and saving content changes back to key files.

It also hosts any number of built-in or 3rd party data source collection backends, which coordinate with ESourceRegistryServer to automatically advertise available data sources on a remote server.

## Details

### E_SOURCE_REGISTRY_SERVER_OBJECT_PATH

    #define             E_SOURCE_REGISTRY_SERVER_OBJECT_PATH

D-Bus object path of the data source server.

Since 3.6

### EDS_REGISTRY_MODULES

    #define EDS_REGISTRY_MODULES    "EDS_REGISTRY_MODULES"

This environment variable configures where the registry server loads it's backend modules from.

### struct ESourceRegistryServer

    struct ESourceRegistryServer;

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

Since 3.6

### e_source_registry_server_new ()

    EDBusServer *       e_source_registry_server_new        (void);

Creates a new instance of ESourceRegistryServer.

Returns : | a new instance of ESourceRegistryServer

Since 3.6

### e_source_registry_server_add_source ()

    void                e_source_registry_server_add_source (ESourceRegistryServer *server,
                                                             ESource *source);

Adds `source` to `server`.

`server` : | an ESourceRegistryServer
`source` : | an ESource

Since 3.6

### e_source_registry_server_remove_source ()

    void                e_source_registry_server_remove_source
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);

Removes `source` and all of its descendants from `server`.

`server` : | an ESourceRegistryServer
`source` : | an ESource

Since 3.6

### enum ESourcePermissionFlags

    typedef enum {
     /*< flags >*/
    	E_SOURCE_PERMISSION_NONE = 0,
    	E_SOURCE_PERMISSION_WRITABLE = 1 << 0,
    	E_SOURCE_PERMISSION_REMOVABLE = 1 << 1
    } ESourcePermissionFlags;

Initial permissions for a newly-loaded data source key file.

`E_SOURCE_PERMISSION_NONE` | The data source gets no initial permissions.
`E_SOURCE_PERMISSION_WRITABLE` | The data source is initially writable.
`E_SOURCE_PERMISSION_REMOVABLE` | The data source is initially removable.

Since 3.6

### e_source_registry_server_load_directory ()

    gboolean            e_source_registry_server_load_directory
                                                            (ESourceRegistryServer *server,
                                                             const gchar *path,
                                                             ESourcePermissionFlags flags,
                                                             GError **error);

Loads data source key files in `path`. Because multiple errors can occur when loading multiple files, `error` is only set if `path` can not be opened. If a key file fails to load, the error is broadcast through the "load-error" signal.

If the E_DBUS_LOAD_DIRECTORY_REMOVABLE flag is given, then the `server` will emit signals on the D-Bus interface when key files are created or deleted in `path`.

`server` : | an ESourceRegistryServer
`path` : | the path to the directory to load
`flags` : | permission flags for files loaded from `path`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if `path` was successfully opened, but this does not imply the key files were successfully loaded

Since 3.6

### e_source_registry_server_load_resource ()

    gboolean            e_source_registry_server_load_resource
                                                            (ESourceRegistryServer *server,
                                                             GResource *resource,
                                                             const gchar *path,
                                                             ESourcePermissionFlags flags,
                                                             GError **error);

Loads data source key files from `resource` by enumerating the children at `path` and calling `e_source_registry_server_load_file()` on each child. Because multiple errors can occur when loading multiple files, `error` is only set if `path` is invalid. If a key file fails to load, the error is broadcast through the "load-error" signal.

`server` : | an ESourceRegistryServer
`resource` : | a GResource containing data source key files
`path` : | the path to the data source key files inside `resource`
`flags` : | permission flags for files loaded from `path`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if `path` was successfully located, but this does not imply the key files were successfully loaded

Since 3.8

### e_source_registry_server_load_file ()

    ESource *           e_source_registry_server_load_file  (ESourceRegistryServer *server,
                                                             GFile *file,
                                                             ESourcePermissionFlags flags,
                                                             GError **error);

Creates an ESource for a native key file and adds it to `server`. If an error occurs, the function returns `NULL` and sets `error`.

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

`server` : | an ESourceRegistryServer
`file` : | the data source key file to load
`flags` : | initial permission flags for the data source
`error` : | return location for a GError, or `NULL`
Returns : | the newly-added ESource, or `NULL` on error

Since 3.6

### e_source_registry_server_load_error ()

    void                e_source_registry_server_load_error (ESourceRegistryServer *server,
                                                             GFile *file,
                                                             const GError *error);

Emits the "load-error" signal.

`server` : | an EBusSourceServer
`file` : | the GFile that failed to load
`error` : | a GError describing the load error

Since 3.6

### e_source_registry_server_ref_source ()

    ESource *           e_source_registry_server_ref_source (ESourceRegistryServer *server,
                                                             const gchar *uid);

Looks up an ESource in `server` by its unique identifier string.

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

`server` : | an ESourceRegistryServer
`uid` : | a unique identifier string
Returns : | an ESource, or `NULL` if no match was found

Since 3.6

### e_source_registry_server_list_sources ()

    GList *             e_source_registry_server_list_sources
                                                            (ESourceRegistryServer *server,
                                                             const gchar *extension_name);

Returns a list of registered sources, sorted by display name. If `extension_name` is given, restrict the list to sources having that extension name.

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

`server` : | an ESourceRegistryServer
`extension_name` : | an extension name, or `NULL`
Returns : | a sorted list of sources

Since 3.6

### e_source_registry_server_find_extension ()

    ESource *           e_source_registry_server_find_extension
                                                            (ESourceRegistryServer *server,
                                                             ESource *source,
                                                             const gchar *extension_name);

Examines `source` and its ancestors and returns the "deepest" ESource having an ESourceExtension with the given `extension_name`. If neither `source` nor any of its ancestors have such an extension, the function returns `NULL`.

This function is useful in cases when an ESourceExtension is meant to apply to both the ESource it belongs to and the ESource's descendants.

A common example is the ESourceCollection extension, where descendants of an ESource having an ESourceCollection extension are implied to be members of that collection. In that example, this function can be used to test whether `source` is a member of a collection.

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

Note the function returns the ESource containing the ESourceExtension instead of the ESourceExtension itself because extension instances are not to be referenced directly (see `e_source_get_extension()`).

`server` : | an ESourceRegistryServer
`source` : | an ESource
`extension_name` : | the extension name to find
Returns : | an ESource, or `NULL` if no match was found

Since 3.8

### e_source_registry_server_ref_backend ()

    ECollectionBackend * e_source_registry_server_ref_backend
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);

Returns the ECollectionBackend associated with `source`, or `NULL` if there is no ECollectionBackend associated with `source`.

An ESource is associated with an ECollectionBackend if the ESource has an ESourceCollection extension, or if it is a hierarchical descendant of another ESource which has an ESourceCollection extension.

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

`server` : | an ESourceRegistryServer
`source` : | an ESource
Returns : | the ECollectionBackend for `source`, or `NULL`

Since 3.6

### e_source_registry_server_ref_backend_factory ()

    ECollectionBackendFactory * e_source_registry_server_ref_backend_factory
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);

returns `NULL`.

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

`server` : | an ESourceRegistryServer
`source` : | an ESource
Returns : | the ECollectionBackendFactory for `source`, or `NULL`

Since 3.6

### e_source_registry_server_new_auth_session ()

    EAuthenticationSession * e_source_registry_server_new_auth_session
                                                            (ESourceRegistryServer *server,
                                                             ESourceAuthenticator *authenticator,
                                                             const gchar *source_uid);

Convenience function instantiates an appropriate authentication session type for `source_uid`.

If `server` has an EServerSideSource instance for `source_uid`, then its "auth-session-type" is used to instantiate a new authentication session. Otherwise a plain EAuthenticationSession is instantiated.

Unreference the returned EAuthenticationSession with `g_object_unref()` when finished with it.

`server` : | an ESourceRegistryServer
`authenticator` : | an ESourceAuthenticator
`source_uid` : | a data source identifier
Returns : | a new EAuthenticationSession for `source_uid`

Since 3.8

### e_source_registry_server_authenticate_sync ()

    gboolean            e_source_registry_server_authenticate_sync
                                                            (ESourceRegistryServer *server,
                                                             EAuthenticationSession *session,
                                                             GCancellable *cancellable,
                                                             GError **error);

Queues the `session` behind any ongoing or pending authentication sessions for the same data source, and eventually executes `session` (see `e_authentication_session_execute_sync()` for more details).

This function blocks until `session` is finished executing. For a non-blocking variation see `e_source_registry_server_authenticate()`.

If an error occurs, the function sets `error` and returns `FALSE`.

`server` : | an ESourceRegistryServer
`session` : | an EAuthenticationSession
`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_source_registry_server_authenticate ()

    void                e_source_registry_server_authenticate
                                                            (ESourceRegistryServer *server,
                                                             EAuthenticationSession *session,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Queues the `session` behind any ongoing or pending authentication sessions for the same data source, and eventually executes `session` (see `e_authentication_session_execute_sync()` for more details).

This function returns immediately after enqueuing `session`. When `session` is finished executing, `callback` will be called. You can then call `e_source_registry_server_authenticate_finish()` to get the result of the operation.

`server` : | an ESourceRegistryServer
`session` : | an EAuthenticationSession
`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_source_registry_server_authenticate_finish ()

    gboolean            e_source_registry_server_authenticate_finish
                                                            (ESourceRegistryServer *server,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_source_registry_server_authenticate()`. If an error occurred, the function will set `error` and return `FALSE`.

`server` : | an ESourceRegistryServer
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_server_load_all ()

    gboolean            e_source_registry_server_load_all   (ESourceRegistryServer *server,
                                                             GError **error);

### Warning

`e_source_registry_server_load_all` has been deprecated since version 3.8 and should not be used in newly-written code. Instead, implement an equivalent function yourself. It was a mistake to encode this much file location policy directly into the library API.

Loads data source key files from standard system-wide and user-specific locations. Because multiple errors can occur when loading multiple files, `error` is only set if a directory can not be opened. If a data source key file fails to load, the error is broadcast through the "load-error" signal.

`server` : | an ESourceRegistryServer
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the standard directories were successfully opened, but this does not imply the key files were successfully loaded

Since 3.6

## Signal Details

### The `"files-loaded"` signal

    void                user_function                      (ESourceRegistryServer *server,
                                                            gpointer               user_data)      : Run Last

Emitted after all data source key files are loaded on startup. Extensions can connect to this signal to perform any additional work prior to running the main loop.

`server` : | the ESourceRegistryServer which emitted the signal
`user_data` : | user data set when the signal handler was connected.

### The `"load-error"` signal

    void                user_function                      (ESourceRegistryServer *server,
                                                            GFile                 *file,
                                                            GError                *error,
                                                            gpointer               user_data)      : Run Last

Emitted when an error occurs while loading or parsing a data source key file.

`server` : | the ESourceRegistryServer which emitted the signal
`file` : | the GFile being loaded
`error` : | a GError describing the error
`user_data` : | user data set when the signal handler was connected.

### The `"source-added"` signal

    void                user_function                      (ESourceRegistryServer *server,
                                                            EServerSideSource     *source,
                                                            gpointer               user_data)      : Run Last

Emitted when an EServerSideSource is added to `server`.

`server` : | the ESourceRegistryServer which emitted the signal
`source` : | the newly-added EServerSideSource
`user_data` : | user data set when the signal handler was connected.

### The `"source-removed"` signal

    void                user_function                      (ESourceRegistryServer *server,
                                                            EServerSideSource     *source,
                                                            gpointer               user_data)      : Run Last

Emitted when an EServerSideSource is removed from `server`.

`server` : | the ESourceRegistryServer which emitted the signal
`source` : | the EServerSideSource that got removed
`user_data` : | user data set when the signal handler was connected.

### The `"tweak-key-file"` signal

    gboolean            user_function                      (ESourceRegistryServer *server,
                                                            GKeyFile              *key_file,
                                                            gchar                 *uid,
                                                            gpointer               user_data)      : Run Last

Emitted from `e_source_registry_server_load_file()` just prior to instantiating an EServerSideSource. Signal handlers can tweak the `key_file` content as necessary and return `TRUE` to write the modified content back to disk.

For the purposes of tweaking, it's easier to deal with a plain GKeyFile than an ESource instance. An ESource, for example, does not allow key file groups to be removed.

The return value is cumulative. If any signal handler returns `TRUE`, the `key_file` content is written back to disk.

`server` : | the ESourceRegistryServer which emitted the signal
`key_file` : | a GKeyFile
`uid` : | a unique identifier string for `key_file`
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if `key_file` was modified, `FALSE` otherwise

Since 3.8