ESourceRegistryServer

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

## Synopsis

    #include <libebackend/libebackend.h>

    #define             E_SOURCE_REGISTRY_SERVER_OBJECT_PATH
    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);
    gboolean            e_source_registry_server_load_all   (ESourceRegistryServer *server,
                                                             GError **error);
    enum                ESourcePermissionFlags;
    gboolean            e_source_registry_server_load_directory
                                                            (ESourceRegistryServer *server,
                                                             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);
    ECollectionBackend * e_source_registry_server_ref_backend
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);
    ECollectionBackendFactory * e_source_registry_server_ref_backend_factory
                                                            (ESourceRegistryServer *server,
                                                             ESource *source);
    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);

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

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

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

### e_source_registry_server_load_all ()

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

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

### 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_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_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 the ECollectionBackendFactory for `source`, if available. If `source` does not have an ESourceCollection extension, or if the ESourceCollection extension names a "backend-name" for which there is no corresponding ECollectionBackendFactory, the function 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_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

## 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 when emitted the signal
`source` : | the EServerSideSource that got removed
`user_data` : | user data set when the signal handler was connected.