contact-system: Add helper method to get a (display) email

Folks uses collection/set objects from libgee to store email addresses
associated with an individual. Unfortunately to extract addresses, parts
of libgee which are unusable from (introspected) bindings have to be
used[0], so add a helper method.

[0] in particular gee_iterator_get(), which is annotated as
    "return: (transfer full): gpointer"

https://bugzilla.gnome.org/show_bug.cgi?id=660580

src/shell-contact-system.c

@@ -315,6 +315,57 @@ shell_contact_system_get_individual (ShellContactSystem *self,
   return FOLKS_INDIVIDUAL (value);
 }
 
+/**
+ * shell_contact_system_get_email_for_display:
+ * @self: A #ShellContactSystem
+ * @individual A #FolksIndividual
+ *
+ * Get an email address (either from IM addresses or email), which can be
+ * used to represent @individual.
+ *
+ * Return: (transfer full): a newly allocated string or %NULL if no address
+ *                          was found
+ */
+char *
+shell_contact_system_get_email_for_display (ShellContactSystem *self,
+                                            FolksIndividual    *individual)
+{
+  GeeMultiMap *im_addr_map = folks_im_details_get_im_addresses (FOLKS_IM_DETAILS (individual));
+  GeeCollection *im_addrs = gee_multi_map_get_values (im_addr_map);
+  GeeSet *email_addrs = folks_email_details_get_email_addresses (FOLKS_EMAIL_DETAILS (individual));
+  GeeIterator *addrs_iter;
+  char *email = NULL;
+
+  addrs_iter = gee_iterable_iterator (GEE_ITERABLE (im_addrs));
+  if (gee_iterator_first (addrs_iter))
+    {
+      FolksImFieldDetails *field = gee_iterator_get (addrs_iter);
+      email = g_strdup (folks_abstract_field_details_get_value ((FolksAbstractFieldDetails*)field));
+
+      g_object_unref (field);
+    }
+
+  g_object_unref (addrs_iter);
+  g_object_unref (im_addrs);
+
+  if (email != NULL)
+    return email;
+
+  addrs_iter = gee_iterable_iterator (GEE_ITERABLE (email_addrs));
+
+  if (gee_iterator_first (addrs_iter))
+    {
+      FolksEmailFieldDetails *field = gee_iterator_get (addrs_iter);
+      email = g_strdup (folks_abstract_field_details_get_value ((FolksAbstractFieldDetails*)field));
+
+      g_object_unref (field);
+    }
+
+  g_object_unref (addrs_iter);
+
+  return email;
+}
+
 /**
  * shell_contact_system_initial_search:
  * @shell: A #ShellContactSystem

src/shell-contact-system.h

@@ -40,6 +40,9 @@ GeeMap *shell_contact_system_get_all (ShellContactSystem *self);
 FolksIndividual *shell_contact_system_get_individual (ShellContactSystem  *self,
                                                       gchar               *id);
 
+char * shell_contact_system_get_email_for_display (ShellContactSystem *self,
+                                                   FolksIndividual    *individual);
+
 GSList * shell_contact_system_initial_search (ShellContactSystem  *shell,
                                               GSList              *terms);