From a86d3aa8f8d26c3c0363447c379ad660cfc0726d Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Mon, 31 Dec 2012 09:02:00 -0500 Subject: [PATCH] Add e_source_registry_server_find_extension(). Server-side equivalent of e_source_registry_find_extension(). Use it in e_source_registry_server_ref_backend(). --- .../reference/libebackend/libebackend-sections.txt | 1 + libebackend/e-source-registry-server.c | 85 ++++++++++++++++------ libebackend/e-source-registry-server.h | 4 + 3 files changed, 66 insertions(+), 24 deletions(-) diff --git a/docs/reference/libebackend/libebackend-sections.txt b/docs/reference/libebackend/libebackend-sections.txt index 177b541..55caacd 100644 --- a/docs/reference/libebackend/libebackend-sections.txt +++ b/docs/reference/libebackend/libebackend-sections.txt @@ -380,6 +380,7 @@ e_source_registry_server_load_file e_source_registry_server_load_error e_source_registry_server_ref_source e_source_registry_server_list_sources +e_source_registry_server_find_extension e_source_registry_server_ref_backend e_source_registry_server_ref_backend_factory e_source_registry_server_authenticate_sync diff --git a/libebackend/e-source-registry-server.c b/libebackend/e-source-registry-server.c index 6b1ec69..753a7f0 100644 --- a/libebackend/e-source-registry-server.c +++ b/libebackend/e-source-registry-server.c @@ -2054,41 +2054,43 @@ e_source_registry_server_list_sources (ESourceRegistryServer *server, } /** - * e_source_registry_server_ref_backend: + * e_source_registry_server_find_extension: * @server: an #ESourceRegistryServer * @source: an #ESource + * @extension_name: the extension name to find * - * Returns the #ECollectionBackend associated with @source, or %NULL if - * there is no #ECollectionBackend associated with @source. + * 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. * - * 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. + * 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. * - * The returned #ECollectionBackend is referenced for thread-safety. - * Unreference the #ECollectionBackend with g_object_unref() when finished - * with it. + * 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. * - * Returns: the #ECollectionBackend for @source, or %NULL + * The returned #ESource is referenced for thread-safety and must be + * unreferenced with g_object_unref() when finished with it. * - * Since: 3.6 + * 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()). + * + * Returns: an #ESource, or %NULL if no match was found + * + * Since: 3.8 **/ -ECollectionBackend * -e_source_registry_server_ref_backend (ESourceRegistryServer *server, - ESource *source) +ESource * +e_source_registry_server_find_extension (ESourceRegistryServer *server, + ESource *source, + const gchar *extension_name) { - ECollectionBackend *backend = NULL; - const gchar *extension_name; - g_return_val_if_fail (E_IS_SOURCE_REGISTRY_SERVER (server), NULL); g_return_val_if_fail (E_IS_SOURCE (source), NULL); - - /* XXX If ESourceRegistryServer ever grows a function similar to - * e_source_registry_find_extension() then we could just use - * that, but despite this use case I think the need for such - * a function is not sufficiently strong yet. */ - - extension_name = E_SOURCE_EXTENSION_COLLECTION; + g_return_val_if_fail (extension_name != NULL, NULL); g_object_ref (source); @@ -2110,6 +2112,41 @@ e_source_registry_server_ref_backend (ESourceRegistryServer *server, break; } + return source; +} + +/** + * e_source_registry_server_ref_backend: + * @server: an #ESourceRegistryServer + * @source: an #ESource + * + * 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. + * + * Returns: the #ECollectionBackend for @source, or %NULL + * + * Since: 3.6 + **/ +ECollectionBackend * +e_source_registry_server_ref_backend (ESourceRegistryServer *server, + ESource *source) +{ + ECollectionBackend *backend = NULL; + + g_return_val_if_fail (E_IS_SOURCE_REGISTRY_SERVER (server), NULL); + g_return_val_if_fail (E_IS_SOURCE (source), NULL); + + source = e_source_registry_server_find_extension ( + server, source, E_SOURCE_EXTENSION_COLLECTION); + if (source != NULL) { backend = g_object_get_data ( G_OBJECT (source), BACKEND_DATA_KEY); diff --git a/libebackend/e-source-registry-server.h b/libebackend/e-source-registry-server.h index f262485..b39a72e 100644 --- a/libebackend/e-source-registry-server.h +++ b/libebackend/e-source-registry-server.h @@ -131,6 +131,10 @@ ESource * e_source_registry_server_ref_source 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, -- 2.7.4