| Evolution-Data-Server Manual: Backend Utilities (libebackend) | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Implemented Interfaces | Signals | ||||
#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);
"files-loaded" :Run Last"load-error" :Run Last"source-added" :Run Last"source-removed" :Run Last
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.
#define E_SOURCE_REGISTRY_SERVER_OBJECT_PATH
D-Bus object path of the data source server.
Since 3.6
struct ESourceRegistryServer;
Contains only private data that should be read and manipulated using the functions below.
Since 3.6
EDBusServer * e_source_registry_server_new (void);
Creates a new instance of ESourceRegistryServer.
Returns : |
a new instance of ESourceRegistryServer |
Since 3.6
void e_source_registry_server_add_source (ESourceRegistryServer *server,ESource *source);
Adds source to server.
|
an ESourceRegistryServer |
|
an ESource |
Since 3.6
void e_source_registry_server_remove_source (ESourceRegistryServer *server,ESource *source);
Removes source and all of its descendants from server.
|
an ESourceRegistryServer |
|
an ESource |
Since 3.6
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.
|
an ESourceRegistryServer |
|
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
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.
| The data source gets no initial permissions. | |
| The data source is initially writable. | |
| The data source is initially removable. |
Since 3.6
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.
|
an ESourceRegistryServer |
|
the path to the directory to load |
|
permission flags for files loaded from path
|
|
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
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.
|
an ESourceRegistryServer |
|
the data source key file to load |
|
initial permission flags for the data source |
|
return location for a GError, or NULL
|
Returns : |
the newly-added ESource, or NULL on error |
Since 3.6
void e_source_registry_server_load_error (ESourceRegistryServer *server,GFile *file,const GError *error);
Emits the "load-error" signal.
|
an EBusSourceServer |
|
the GFile that failed to load |
|
a GError describing the load error |
Since 3.6
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.
|
an ESourceRegistryServer |
|
a unique identifier string |
Returns : |
an ESource, or NULL if no match was found |
Since 3.6
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); |
|
an ESourceRegistryServer |
|
an extension name, or NULL
|
Returns : |
a sorted list of sources |
Since 3.6
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.
|
an ESourceRegistryServer |
|
an ESource |
Returns : |
the ECollectionBackend for source, or NULL
|
Since 3.6
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.
|
an ESourceRegistryServer |
|
an ESource |
Returns : |
the ECollectionBackendFactory for source, or NULL
|
Since 3.6
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.
|
an ESourceRegistryServer |
|
an EAuthenticationSession |
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.6
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.
|
an ESourceRegistryServer |
|
an EAuthenticationSession |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.6
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.
|
an ESourceRegistryServer |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.6
"files-loaded" signalvoid 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.
|
the ESourceRegistryServer which emitted the signal |
|
user data set when the signal handler was connected. |
"load-error" signalvoid 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.
|
the ESourceRegistryServer which emitted the signal |
|
the GFile being loaded |
|
a GError describing the error |
|
user data set when the signal handler was connected. |
"source-added" signalvoid user_function (ESourceRegistryServer *server,
EServerSideSource *source,
gpointer user_data) : Run Last
Emitted when an EServerSideSource is added to server.
|
the ESourceRegistryServer which emitted the signal |
|
the newly-added EServerSideSource |
|
user data set when the signal handler was connected. |
"source-removed" signalvoid user_function (ESourceRegistryServer *server,
EServerSideSource *source,
gpointer user_data) : Run Last
Emitted when an EServerSideSource is removed from server.
|
the ESourceRegistryServer when emitted the signal |
|
the EServerSideSource that got removed |
|
user data set when the signal handler was connected. |