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

[Matthew Barnes <mbarnes src gnome org>]

commit 2dff25924c1d5996f864af8e19818405c58a82cc
Author: Matthew Barnes <mbarnes redhat com>
Date:   Tue Aug 21 10:46:52 2012 -0400

    Add e_collection_backend_dup_resource_id().
    
    Extracts the resource ID for a child source, which is supposed to be a
    stable and unique server-assigned identifier for the remote resource
    described by the child source.  If the child source is not actually a
    child of the collection backend, the function returns NULL.

 .../reference/libebackend/libebackend-sections.txt |    1 +
 libebackend/e-collection-backend.c                 |   52 ++++++++++++++++++++
 libebackend/e-collection-backend.h                 |    3 +
 3 files changed, 56 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/libebackend/libebackend-sections.txt b/docs/reference/libebackend/libebackend-sections.txt
index 269651e..8337e13 100644
--- a/docs/reference/libebackend/libebackend-sections.txt
+++ b/docs/reference/libebackend/libebackend-sections.txt
@@ -118,6 +118,7 @@ ECollectionBackend
 e_collection_backend_new_child
 e_collection_backend_ref_server
 e_collection_backend_get_cache_dir
+e_collection_backend_dup_resource_id
 e_collection_backend_claim_all_resources
 e_collection_backend_list_calendar_sources
 e_collection_backend_list_contacts_sources
diff --git a/libebackend/e-collection-backend.c b/libebackend/e-collection-backend.c
index e6a280c..cfb75ea 100644
--- a/libebackend/e-collection-backend.c
+++ b/libebackend/e-collection-backend.c
@@ -1020,6 +1020,58 @@ e_collection_backend_get_cache_dir (ECollectionBackend *backend)
 }
 
 /**
+ * e_collection_backend_dup_resource_id:
+ * @backend: an #ECollectionBackend
+ * @child_source: an #ESource managed by @backend
+ *
+ * Extracts the resource ID for @child_source, which is supposed to be a
+ * stable and unique server-assigned identifier for the remote resource
+ * described by @child_source.  If @child_source is not actually a child
+ * of the collection #EBackend:source owned by @backend, the function
+ * returns %NULL.
+ *
+ * The returned string should be freed with g_free() when no longer needed.
+ *
+ * Returns: a newly-allocated resource ID for @child_source, or %NULL
+ *
+ * Since: 3.6
+ **/
+gchar *
+e_collection_backend_dup_resource_id (ECollectionBackend *backend,
+                                      ESource *child_source)
+{
+	ECollectionBackend *backend_for_child_source;
+	ECollectionBackendClass *class;
+	ESourceRegistryServer *server;
+	gboolean child_is_ours = FALSE;
+
+	g_return_val_if_fail (E_IS_COLLECTION_BACKEND (backend), NULL);
+	g_return_val_if_fail (E_IS_SOURCE (child_source), NULL);
+
+	class = E_COLLECTION_BACKEND_GET_CLASS (backend);
+	g_return_val_if_fail (class->dup_resource_id != NULL, NULL);
+
+	/* Make sure the ESource belongs to the ECollectionBackend to
+	 * avoid accidentally creating a new extension while trying to
+	 * extract a resource ID that isn't there.  Better to test this
+	 * up front than rely on ECollectionBackend subclasses to do it. */
+	server = e_collection_backend_ref_server (backend);
+	backend_for_child_source =
+		e_source_registry_server_ref_backend (server, child_source);
+	g_object_unref (server);
+
+	if (backend_for_child_source != NULL) {
+		child_is_ours = (backend_for_child_source == backend);
+		g_object_unref (backend_for_child_source);
+	}
+
+	if (!child_is_ours)
+		return NULL;
+
+	return class->dup_resource_id (backend, child_source);
+}
+
+/**
  * e_collection_backend_claim_all_resources:
  * @backend: an #ECollectionBackend
  *
diff --git a/libebackend/e-collection-backend.h b/libebackend/e-collection-backend.h
index 8f97691..1ebcd7f 100644
--- a/libebackend/e-collection-backend.h
+++ b/libebackend/e-collection-backend.h
@@ -117,6 +117,9 @@ struct _ESourceRegistryServer *
 		e_collection_backend_ref_server	(ECollectionBackend *backend);
 const gchar *	e_collection_backend_get_cache_dir
 						(ECollectionBackend *backend);
+gchar *		e_collection_backend_dup_resource_id
+						(ECollectionBackend *backend,
+						 ESource *child_source);
 GList *		e_collection_backend_claim_all_resources
 						(ECollectionBackend *backend);
 GList *		e_collection_backend_list_calendar_sources