Top |
Functions
Description
The ESourceRegistry is a global singleton store for all ESource instances. It uses file monitors to react to key file creation and deletion events, either constructing an ESource instance from the newly created key file, or removing from the logical ESource hierarchy the instance corresponding to the deleted key file.
The ESourceRegistry can be queried for individual ESource instances by their unique identifier string or key file path, for collections of ESource instances having a particular extension, or for all available ESource instances.
The ESourceRegistry API also provides a front-end for the "org.gnome.Evolution.DefaultSources" GSettings schema which tracks which ESource instances are designated to be the user's default address book, calendar, memo list and task list for desktop integration.
Note: The ESourceRegistry uses thread default main context from the time of its creation to deliver D-Bus signals, finish operations and so on, thus it requires a running main loop for its proper functionality.
Functions
e_source_registry_new_sync ()
ESourceRegistry * e_source_registry_new_sync (GCancellable *cancellable
,GError **error
);
Creates a new ESourceRegistry front-end for the registry D-Bus service.
If an error occurs in connecting to the D-Bus service, the function sets
error
and returns NULL
.
Since 3.12 a singleton will be returned. No strong reference is kept internally, so it is the caller's responsibility to keep one.
Since: 3.6
e_source_registry_new ()
void e_source_registry_new (GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously creates a new ESourceRegistry front-end for the registry D-Bus service.
When the operation is finished, callback
will be called. You can then
call e_source_registry_new_finish()
to get the result of the operation.
Since 3.12 a singleton will be returned. No strong reference is kept internally, so it is the caller's responsibility to keep one.
Parameters
cancellable |
optional GCancellable object, or |
[allow-none] |
callback |
a GAsyncReadyCallback to call when the request is satisfied. |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.6
e_source_registry_new_finish ()
ESourceRegistry * e_source_registry_new_finish (GAsyncResult *result
,GError **error
);
Finishes the operation started with e_source_registry_new_finish()
.
If an error occurs in connecting to the D-Bus service, the function
sets error
and returns NULL
.
Since: 3.6
e_source_registry_commit_source_sync ()
gboolean e_source_registry_commit_source_sync (ESourceRegistry *registry
,ESource *source
,GCancellable *cancellable
,GError **error
);
This is a convenience function intended for use with graphical
ESource editors. Call this function when the user is finished
making changes to source
.
If source
has a GDBusObject, its contents are submitted to the D-Bus
service through e_source_write_sync()
.
If source
does NOT have a GDBusObject (implying it's a scratch
ESource), its contents are submitted to the D-Bus service through
either e_source_remote_create_sync()
if source
is to be a collection
member, or e_source_registry_create_sources_sync()
if source
to be an
independent data source.
If an error occurs, the function will set error
and return FALSE
.
Parameters
registry |
||
source |
an ESource with changes to commit |
|
cancellable |
optional GCancellable object, or |
[allow-none] |
error |
Since: 3.6
e_source_registry_commit_source ()
void e_source_registry_commit_source (ESourceRegistry *registry
,ESource *source
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
See e_source_registry_commit_source_sync()
for details.
When the operation is finished, callback
will be called. You can then
call e_source_registry_commit_source_finish()
to get the result of the
operation.
Parameters
registry |
||
source |
an ESource with changes to commit |
|
cancellable |
optional GCancellable object, or |
[allow-none] |
callback |
a GAsyncReadyCallback to call when the request is satisfied. |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.6
e_source_registry_commit_source_finish ()
gboolean e_source_registry_commit_source_finish (ESourceRegistry *registry
,GAsyncResult *result
,GError **error
);
Finishes the operation started with e_source_registry_commit_source()
.
If an error occurred, the function will set error
and return FALSE
.
Since: 3.6
e_source_registry_create_sources_sync ()
gboolean e_source_registry_create_sources_sync (ESourceRegistry *registry
,GList *list_of_sources
,GCancellable *cancellable
,GError **error
);
Requests the D-Bus service create new key files for each ESource in
list_of_sources
. Each list element must be a scratch ESource with
no GDBusObject.
If an error occurs, the function will set error
and return FALSE
.
Parameters
registry |
||
list_of_sources |
a list of ESource instances with no GDBusObject. |
[element-type ESource] |
cancellable |
optional GCancellable object, or |
[allow-none] |
error |
Since: 3.6
e_source_registry_create_sources ()
void e_source_registry_create_sources (ESourceRegistry *registry
,GList *list_of_sources
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously requests the D-Bus service create new key files for each
ESource in list_of_sources
. Each list element must be a scratch
ESource with no GDBusObject.
When the operation is finished, callback
will be called. You can then
call e_source_registry_create_sources_finish()
to get the result of the
operation.
Parameters
registry |
||
list_of_sources |
a list of ESource instances with no GDBusObject. |
[element-type ESource] |
cancellable |
optional GCancellable object, or |
[allow-none] |
callback |
a GAsyncReadyCallback to call when the request is satisfied. |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.6
e_source_registry_create_sources_finish ()
gboolean e_source_registry_create_sources_finish (ESourceRegistry *registry
,GAsyncResult *result
,GError **error
);
Finishes the operation started with e_source_registry_create_sources()
.
If an error occurred, the function will set error
and return FALSE
.
Since: 3.6
e_source_registry_ref_source ()
ESource * e_source_registry_ref_source (ESourceRegistry *registry
,const gchar *uid
);
Looks up an ESource in registry
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.
Since: 3.6
e_source_registry_list_sources ()
GList * e_source_registry_list_sources (ESourceRegistry *registry
,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 list 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); |
Since: 3.6
e_source_registry_list_enabled ()
GList * e_source_registry_list_enabled (ESourceRegistry *registry
,const gchar *extension_name
);
Similar to e_source_registry_list_sources()
, but returns only enabled
sources according to e_source_registry_check_enabled()
.
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 list 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); |
Since: 3.10
e_source_registry_find_extension ()
ESource * e_source_registry_find_extension (ESourceRegistry *registry
,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()
).
Since: 3.6
e_source_registry_check_enabled ()
gboolean e_source_registry_check_enabled (ESourceRegistry *registry
,ESource *source
);
Determines whether source
is "effectively" enabled by examining its
own “enabled” property as well as those of its ancestors in the
ESource hierarchy. If all examined “enabled” properties are
TRUE
, then the function returns TRUE
. If any are FALSE
, then the
function returns FALSE
.
Use this function instead of e_source_get_enabled()
to determine
things like whether to display an ESource in a user interface or
whether to act on the data set described by the ESource.
Since: 3.8
e_source_registry_build_display_tree ()
GNode * e_source_registry_build_display_tree (ESourceRegistry *registry
,const gchar *extension_name
);
Returns a single GNode tree of registered sources that can be used to populate a GtkTreeModel. (The root GNode is just an empty placeholder.)
Similar to e_source_registry_list_sources()
, an extension_name
can be
given to restrict the tree to sources having that extension name. Parents
of matched sources are included in the tree regardless of whether they have
an extension named extension_name
.
Disabled leaf nodes are automatically excluded from the GNode tree.
The sources returned in the tree are referenced for thread-safety.
They must each be unreferenced with g_object_unref()
when finished
with them. Free the returned tree itself with g_node_destroy()
.
For convenience, e_source_registry_free_display_tree()
does all
that in one step.
Since: 3.6
e_source_registry_free_display_tree ()
void
e_source_registry_free_display_tree (GNode *display_tree
);
Convenience function to free a GNode tree of registered
sources created by e_source_registry_build_display_tree()
.
Since: 3.6
e_source_registry_dup_unique_display_name ()
gchar * e_source_registry_dup_unique_display_name (ESourceRegistry *registry
,ESource *source
,const gchar *extension_name
);
Compares source
's “display-name” against other sources having
an ESourceExtension named extension_name
, if given, or else against
all other sources in the registry
.
If sources
's “display-name” is unique among these other sources,
the function will return the “display-name” verbatim. Otherwise
the function will construct a string that includes the sources
's own
“display-name” as well as those of its ancestors.
The function's return value is intended to be used in messages shown to
the user to help clarify which source is being referred to. It assumes
source
's “display-name” is at least unique among its siblings.
Free the returned string with g_free()
when finished with it.
Since: 3.8
e_source_registry_debug_dump ()
void e_source_registry_debug_dump (ESourceRegistry *registry
,const gchar *extension_name
);
Handy debugging function that uses e_source_registry_build_display_tree()
to print a tree of registered sources to standard output.
Since: 3.6
e_source_registry_ref_builtin_address_book ()
ESource *
e_source_registry_ref_builtin_address_book
(ESourceRegistry *registry
);
Returns the built-in address book ESource.
This ESource is always present and makes for a safe fallback.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_ref_builtin_calendar ()
ESource *
e_source_registry_ref_builtin_calendar
(ESourceRegistry *registry
);
Returns the built-in calendar ESource.
This ESource is always present and makes for a safe fallback.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_ref_builtin_mail_account ()
ESource *
e_source_registry_ref_builtin_mail_account
(ESourceRegistry *registry
);
Returns the built-in mail account ESource.
This ESource is always present and makes for a safe fallback.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_ref_builtin_memo_list ()
ESource *
e_source_registry_ref_builtin_memo_list
(ESourceRegistry *registry
);
Returns the built-in memo list ESource.
This ESource is always present and makes for a safe fallback.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_ref_builtin_proxy ()
ESource *
e_source_registry_ref_builtin_proxy (ESourceRegistry *registry
);
Returns the built-in proxy profile ESource.
This ESource is always present and makes for a safe fallback.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.12
e_source_registry_ref_builtin_task_list ()
ESource *
e_source_registry_ref_builtin_task_list
(ESourceRegistry *registry
);
Returns the built-in task list ESource.
This ESource is always present and makes for a safe fallback.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_ref_default_address_book ()
ESource *
e_source_registry_ref_default_address_book
(ESourceRegistry *registry
);
Returns the ESource most recently passed to
e_source_registry_set_default_address_book()
either in this session
or a previous session, or else falls back to the built-in address book.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_address_book ()
void e_source_registry_set_default_address_book (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default address book. If default_source
is NULL
, the default address book is reset to the built-in address book.
This setting will persist across sessions until changed.
Since: 3.6
e_source_registry_ref_default_calendar ()
ESource *
e_source_registry_ref_default_calendar
(ESourceRegistry *registry
);
Returns the ESource most recently passed to
e_source_registry_set_default_calendar()
either in this session
or a previous session, or else falls back to the built-in calendar.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_calendar ()
void e_source_registry_set_default_calendar (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default calendar. If default_source
is NULL
, the default calendar is reset to the built-in calendar.
This setting will persist across sessions until changed.
Since: 3.6
e_source_registry_ref_default_mail_account ()
ESource *
e_source_registry_ref_default_mail_account
(ESourceRegistry *registry
);
Returns the ESource most recently passed to
e_source_registry_set_default_mail_account()
either in this session
or a previous session, or else falls back to the built-in mail account.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_mail_account ()
void e_source_registry_set_default_mail_account (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default mail account. If default_source
is NULL
, the default mail account is reset to the built-in mail account.
This setting will persist across sessions until changed.
Since: 3.6
e_source_registry_ref_default_mail_identity ()
ESource *
e_source_registry_ref_default_mail_identity
(ESourceRegistry *registry
);
Returns the ESource most recently passed to
e_source_registry_set_default_mail_identity()
either in this session
or a previous session, or else falls back to the mail identity named
by the default mail account. If even that fails it returns any mail
identity from registry
, or NULL
if there are none.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_mail_identity ()
void e_source_registry_set_default_mail_identity (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default mail identity. If default_source
is NULL
, the next request for the default mail identity will use the
fallbacks described in e_source_registry_ref_default_mail_identity()
.
Since: 3.6
e_source_registry_ref_default_memo_list ()
ESource *
e_source_registry_ref_default_memo_list
(ESourceRegistry *registry
);
Returns the ESource most recently passed to
e_source_registry_set_default_memo_list()
either in this session
or a previous session, or else falls back to the built-in memo list.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_memo_list ()
void e_source_registry_set_default_memo_list (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default memo list. If default_source
is NULL
, the default memo list is reset to the built-in memo list.
This setting will persist across sessions until changed.
Since: 3.6
e_source_registry_ref_default_task_list ()
ESource *
e_source_registry_ref_default_task_list
(ESourceRegistry *registry
);
Returns the ESource most recently passed to
e_source_registry_set_default_task_list()
either in this session
or a previous session, or else falls back to the built-in task list.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_task_list ()
void e_source_registry_set_default_task_list (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default task list. If default_source
is NULL
, the default task list is reset to the built-in task list.
This setting will persist across sessions until changed.
Since: 3.6
e_source_registry_ref_default_for_extension_name ()
ESource * e_source_registry_ref_default_for_extension_name (ESourceRegistry *registry
,const gchar *extension_name
);
This is a convenience function to return a default ESource based on
extension_name
. This only works with a subset of extension names.
If extension_name
is E_SOURCE_EXTENSION_ADDRESS_BOOK, the function
returns the current default address book, or else falls back to the
built-in address book.
If extension_name
is E_SOURCE_EXTENSION_CALENDAR, the function returns
the current default calendar, or else falls back to the built-in calendar.
If extension_name
is E_SOURCE_EXTENSION_MAIL_ACCOUNT, the function
returns the current default mail account, or else falls back to the
built-in mail account.
If extension_name
is E_SOURCE_EXTENSION_MAIL_IDENTITY, the function
returns the current default mail identity, or else falls back to the
mail identity named by the current default mail account.
If extension_name
is E_SOURCE_EXTENSION_MEMO_LIST, the function returns
the current default memo list, or else falls back to the built-in memo list.
If extension_name
is E_SOURCE_EXTENSION_TASK_LIST, the function returns
the current default task list, or else falls back to the built-in task list.
For all other values of extension_name
, the function returns NULL
.
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
when finished with it.
Since: 3.6
e_source_registry_set_default_for_extension_name ()
void e_source_registry_set_default_for_extension_name (ESourceRegistry *registry
,const gchar *extension_name
,ESource *default_source
);
This is a convenience function to set a default ESource based on
extension_name
. This only works with a subset of extension names.
If extension_name
is E_SOURCE_EXTENSION_ADDRESS_BOOK, the function
sets default_source
as the default address book. If default_source
is NULL
, the default address book is reset to the built-in address book.
If extension_name
is E_SOURCE_EXTENSION_CALENDAR, the function sets
default_source
as the default calendar. If default_source
is NULL
,
the default calendar is reset to the built-in calendar.
If extension_name
is E_SOURCE_EXTENSION_MAIL_ACCOUNT, the function
sets default_source
as the default mail account. If default_source
is NULL
, the default mail account is reset to the built-in mail account.
If extension_name
is E_SOURCE_EXTENSION_MAIL_IDENTITY, the function
sets default_source
as the default mail identity. If default_source
is NULL
, the next request for the default mail identity will return
the mail identity named by the default mail account.
If extension_name
is E_SOURCE_EXTENSION_MEMO_LIST, the function sets
default_source
as the default memo list. If default_source
is NULL
,
the default memo list is reset to the built-in memo list.
If extension_name
is E_SOURCE_EXTENSION_TASK_LIST, the function sets
default_source
as the default task list. If default_source
is NULL
,
the default task list is reset to the built-in task list.
For all other values of extension_name
, the function does nothing.
Since: 3.6
Types and Values
struct ESourceRegistry
struct ESourceRegistry;
Contains only private data that should be read and manipulated using the functions below.
Since: 3.6