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;
struct              ESourceRegistryServerClass;
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_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);

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 {
	EDataFactory parent;
	ESourceRegistryServerPrivate *priv;
};

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

Since 3.6


struct ESourceRegistryServerClass

struct ESourceRegistryServerClass {
	EDataFactoryClass parent_class;

	/* Signals */
	void		(*load_error)		(ESourceRegistryServer *server,
						 GFile *file,
						 const GError *error);
	void		(*files_loaded)		(ESourceRegistryServer *server);
	void		(*source_added)		(ESourceRegistryServer *server,
						 ESource *source);
	void		(*source_removed) (ESourceRegistryServer *server,
						 ESource *source);
	gboolean (*tweak_key_file) (ESourceRegistryServer *server,
						 GKeyFile *key_file,
						 const gchar *uid);

	/* Reserved slots. */
	gpointer reserved[16];
};

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