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

[Matthew Barnes <mbarnes src gnome org>]

commit dfc2f308fd7e934114780423a3c30f5b8c7f3df6
Author: Matthew Barnes <mbarnes redhat com>
Date:   Sat Feb 23 08:45:40 2013 -0500

    Add e_source_registry_dup_unique_display_name().
    
    Compares a source's display name against other sources having an
    extension with the given extension name, or else against all other
    sources in the registry if no extension name was given.
    
    If the source's display name is unique among these other sources, the
    function will return the source's display name verbatim.  Otherwise the
    function will construct a string that includes the source's own display
    name as well as those of its ancestors.
    
    The functions'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
    the source's display name is at least unique among its siblings.

 .../libedataserver/libedataserver-sections.txt     |    1 +
 libedataserver/e-source-registry.c                 |  111 ++++++++++++++++++++
 libedataserver/e-source-registry.h                 |    4 +
 3 files changed, 116 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/libedataserver/libedataserver-sections.txt 
b/docs/reference/libedataserver/libedataserver-sections.txt
index 1ca5533..71a8415 100644
--- a/docs/reference/libedataserver/libedataserver-sections.txt
+++ b/docs/reference/libedataserver/libedataserver-sections.txt
@@ -850,6 +850,7 @@ e_source_registry_find_extension
 e_source_registry_check_enabled
 e_source_registry_build_display_tree
 e_source_registry_free_display_tree
+e_source_registry_dup_unique_display_name
 e_source_registry_debug_dump
 e_source_registry_ref_builtin_address_book
 e_source_registry_ref_default_address_book
diff --git a/libedataserver/e-source-registry.c b/libedataserver/e-source-registry.c
index ab9b946..cd2da0f 100644
--- a/libedataserver/e-source-registry.c
+++ b/libedataserver/e-source-registry.c
@@ -2666,6 +2666,117 @@ e_source_registry_free_display_tree (GNode *display_tree)
        g_node_destroy (display_tree);
 }
 
+/**
+ * e_source_registry_dup_unique_display_name:
+ * @registry: an #ESourceRegistry
+ * @source: an #ESource
+ * @extension_name: (allow-none): an extension name, or %NULL
+ *
+ * Compares @source's #ESource: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 #ESource:display-name is unique among these other sources,
+ * the function will return the #ESource:display-name verbatim.  Otherwise
+ * the function will construct a string that includes the @sources's own
+ * #ESource: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 #ESource:display-name is at least unique among its siblings.
+ *
+ * Free the returned string with g_free() when finished with it.
+ *
+ * Returns: a unique display name for @source
+ *
+ * Since: 3.8
+ **/
+gchar *
+e_source_registry_dup_unique_display_name (ESourceRegistry *registry,
+                                           ESource *source,
+                                           const gchar *extension_name)
+{
+       GString *buffer;
+       GList *list, *link;
+       gchar *display_name;
+       gboolean need_clarification = FALSE;
+
+       g_return_val_if_fail (E_IS_SOURCE_REGISTRY (registry), NULL);
+       g_return_val_if_fail (E_IS_SOURCE (source), NULL);
+
+       list = e_source_registry_list_sources (registry, extension_name);
+
+       /* Remove the input source from the list, if present. */
+       link = g_list_find (list, source);
+       if (link != NULL) {
+               g_object_unref (link->data);
+               list = g_list_remove_link (list, link);
+       }
+
+       /* Now find another source with a matching display name. */
+       link = g_list_find_custom (
+               list, source, (GCompareFunc)
+               e_source_compare_by_display_name);
+
+       need_clarification = (link != NULL);
+
+       g_list_free_full (list, (GDestroyNotify) g_object_unref);
+       list = NULL;
+
+       display_name = e_source_dup_display_name (source);
+       buffer = g_string_new (display_name);
+       g_free (display_name);
+
+       if (need_clarification) {
+               /* Build a list of ancestor sources. */
+
+               g_object_ref (source);
+
+               while (source != NULL) {
+                       gchar *parent_uid;
+
+                       parent_uid = e_source_dup_parent (source);
+
+                       g_object_unref (source);
+                       source = NULL;
+
+                       if (parent_uid != NULL) {
+                               source = e_source_registry_ref_source (
+                                       registry, parent_uid);
+                               g_free (parent_uid);
+                       }
+
+                       if (source != NULL) {
+                               g_object_ref (source);
+                               list = g_list_prepend (list, source);
+                       }
+               }
+
+               /* Display the ancestor names from the most distant
+                * ancestor to the input source's immediate parent. */
+
+               if (list != NULL)
+                       g_string_append (buffer, " (");
+
+               for (link = list; link != NULL; link = g_list_next (link)) {
+                       if (link != list)
+                               g_string_append (buffer, " / ");
+
+                       source = E_SOURCE (link->data);
+                       display_name = e_source_dup_display_name (source);
+                       g_string_append (buffer, display_name);
+                       g_free (display_name);
+               }
+
+               if (list != NULL)
+                       g_string_append (buffer, ")");
+
+               g_list_free_full (list, (GDestroyNotify) g_object_unref);
+       }
+
+       return g_string_free (buffer, FALSE);
+}
+
 /* Helper for e_source_registry_debug_dump() */
 static gboolean
 source_registry_debug_dump_cb (GNode *node)
diff --git a/libedataserver/e-source-registry.h b/libedataserver/e-source-registry.h
index 5a2a6fe..1c15f5c 100644
--- a/libedataserver/e-source-registry.h
+++ b/libedataserver/e-source-registry.h
@@ -150,6 +150,10 @@ GNode *            e_source_registry_build_display_tree
                                                 const gchar *extension_name);
 void           e_source_registry_free_display_tree
                                                (GNode *display_tree);
+gchar *                e_source_registry_dup_unique_display_name
+                                               (ESourceRegistry *registry,
+                                                ESource *source,
+                                                const gchar *extension_name);
 void           e_source_registry_debug_dump    (ESourceRegistry *registry,
                                                 const gchar *extension_name);