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);
void                e_source_registry_server_queue_auth_session
                                                        (ESourceRegistryServer *server,
                                                         EAuthenticationSession *session);
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);
ECollectionBackendFactory * e_source_registry_server_ref_backend_factory
                                                        (ESourceRegistryServer *server,
                                                         ESource *source);

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

void                e_source_registry_server_queue_auth_session
                                                        (ESourceRegistryServer *server,
                                                         EAuthenticationSession *session);

Queues an authentication session. When its turn comes, and if necessary, the user will be prompted for a secret. Sessions are queued this way to prevent user prompts from piling up on the screen.

server :

an ESourceRegistryServer

session :

an EDBusSourceAuthenticator

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:

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

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.