Top | ![]() |
![]() |
![]() |
![]() |
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"
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.
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.
cancellable |
optional |
[allow-none] |
error |
return location for a |
Since: 3.6
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.
cancellable |
optional |
[allow-none] |
callback |
a |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.6
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
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 e_source_write_sync()
.
If source
does NOT have a 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
registry |
||
source |
an ESource with changes to commit |
|
cancellable |
optional |
[allow-none] |
error |
return location for |
Since: 3.6
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.
registry |
||
source |
an ESource with changes to commit |
|
cancellable |
optional |
[allow-none] |
callback |
a |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.6
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
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
If an error occurs, the function will set error
and return FALSE
registry |
||
list_of_sources |
a list of ESource instances with
no |
[element-type ESource] |
cancellable |
optional |
[allow-none] |
error |
return location for a |
Since: 3.6
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
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.
registry |
||
list_of_sources |
a list of ESource instances with
no |
[element-type ESource] |
cancellable |
optional |
[allow-none] |
callback |
a |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.6
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
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()
Since: 3.6
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()
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);
Since: 3.6
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()
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);
Since: 3.10
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()
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
gboolean e_source_registry_check_enabled (ESourceRegistry *registry
,ESource *source
);
Determines whether source
is "effectively" enabled by examining its
own TRUE
TRUE
FALSE
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
GNode * e_source_registry_build_display_tree (ESourceRegistry *registry
,const
);gchar *extension_name
Returns a single
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
The sources returned in the tree are referenced for thread-safety.
They must each be unreferenced with g_object_unref()
g_node_destroy()
e_source_registry_free_display_tree()
does all
that in one step.
[skip]
Since: 3.6
void e_source_registry_free_display_tree ();
GNode *display_tree
Convenience function to free a e_source_registry_build_display_tree()
.
Since: 3.6
gchar * e_source_registry_dup_unique_display_name (ESourceRegistry *registry
,ESource *source
,const
);gchar *extension_name
Compares source
's extension_name
, if given, or else against
all other sources in the registry
.
If sources
's sources
's own
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
Free the returned string with g_free()
Since: 3.8
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
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()
Since: 3.6
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()
Since: 3.6
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()
Since: 3.6
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()
Since: 3.6
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()
Since: 3.12
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()
Since: 3.6
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()
Since: 3.6
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
Since: 3.6
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()
Since: 3.6
void e_source_registry_set_default_calendar (ESourceRegistry *registry
,ESource *default_source
);
Sets default_source
as the default calendar. If default_source
is NULL
Since: 3.6
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()
Since: 3.6
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
Since: 3.6
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
The returned ESource is referenced for thread-safety and must be
unreferenced with g_object_unref()
Since: 3.6
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
e_source_registry_ref_default_mail_identity()
.
Since: 3.6
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()
Since: 3.6
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
Since: 3.6
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()
Since: 3.6
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
Since: 3.6
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()
Since: 3.6
void e_source_registry_set_default_for_extension_name (ESourceRegistry *registry
,const
,gchar *extension_nameESource *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
If extension_name
is E_SOURCE_EXTENSION_CALENDAR, the function sets
default_source
as the default calendar. If default_source
is NULL
If extension_name
is E_SOURCE_EXTENSION_MAIL_ACCOUNT, the function
sets default_source
as the default mail account. If default_source
is NULL
If extension_name
is E_SOURCE_EXTENSION_MAIL_IDENTITY, the function
sets default_source
as the default mail identity. If default_source
is NULL
If extension_name
is E_SOURCE_EXTENSION_MEMO_LIST, the function sets
default_source
as the default memo list. If default_source
is NULL
If extension_name
is E_SOURCE_EXTENSION_TASK_LIST, the function sets
default_source
as the default task list. If default_source
is NULL
For all other values of extension_name
, the function does nothing.
registry |
||
extension_name |
an extension name |
|
default_source |
an ESource, or |
[allow-none] |
Since: 3.6
struct ESourceRegistry { };
Contains only private data that should be read and manipulated using the functions below.
Since: 3.6