[evolution-data-server] Add e_source_registry_server_find_extension().

[Matthew Barnes <mbarnes src gnome org>]

commit a86d3aa8f8d26c3c0363447c379ad660cfc0726d
Author: Matthew Barnes <mbarnes redhat com>
Date:   Mon Dec 31 09:02:00 2012 -0500

    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,