[evolution] Add e_client_selector_ref_cached_client_by_iter().

[Matthew Barnes <mbarnes src gnome org>]

commit 5488c24819de10d0b9c4dc1c512adc859d47a777
Author: Matthew Barnes <mbarnes redhat com>
Date:   Wed Feb 20 12:48:46 2013 -0500

    Add e_client_selector_ref_cached_client_by_iter().

 doc/reference/libeutil/libeutil-sections.txt |    1 +
 e-util/e-client-selector.c                   |   37 ++++++++++++++++++++++++++
 e-util/e-client-selector.h                   |    3 ++
 3 files changed, 41 insertions(+), 0 deletions(-)
---
diff --git a/doc/reference/libeutil/libeutil-sections.txt b/doc/reference/libeutil/libeutil-sections.txt
index f4eee6f..ca98eb5 100644
--- a/doc/reference/libeutil/libeutil-sections.txt
+++ b/doc/reference/libeutil/libeutil-sections.txt
@@ -1284,6 +1284,7 @@ e_client_selector_get_client_sync
 e_client_selector_get_client
 e_client_selector_get_client_finish
 e_client_selector_ref_cached_client
+e_client_selector_ref_cached_client_by_iter
 e_client_selector_is_backend_dead
 <SUBSECTION Standard>
 E_CLIENT_SELECTOR
diff --git a/e-util/e-client-selector.c b/e-util/e-client-selector.c
index a38cc38..1b753f5 100644
--- a/e-util/e-client-selector.c
+++ b/e-util/e-client-selector.c
@@ -418,6 +418,43 @@ e_client_selector_ref_cached_client (EClientSelector *selector,
 }
 
 /**
+ * e_client_selector_ref_cached_client_by_iter:
+ * @selector: an #EClientSelector
+ * @iter: a #GtkTreeIter
+ *
+ * Returns a shared #EClient instance for the #ESource in the tree model
+ * row pointed to by @iter and the value of #ESourceSelector:extension-name
+ * if such an instance is already cached, or else %NULL.  This function does
+ * not create a new #EClient instance, and therefore does not block.
+ *
+ * The returned #EClient is referenced for thread-safety and must be
+ * unreferenced with g_object_unref() when finished with it.
+ *
+ * Returns: an #EClient, or %NULL
+ **/
+EClient *
+e_client_selector_ref_cached_client_by_iter (EClientSelector *selector,
+                                             GtkTreeIter *iter)
+{
+       EClient *client = NULL;
+       ESource *source;
+
+       g_return_val_if_fail (E_IS_CLIENT_SELECTOR (selector), NULL);
+       g_return_val_if_fail (iter != NULL, NULL);
+
+       source = e_source_selector_ref_source_by_iter (
+               E_SOURCE_SELECTOR (selector), iter);
+
+       if (source != NULL) {
+               client = e_client_selector_ref_cached_client (
+                       selector, source);
+               g_object_unref (source);
+       }
+
+       return client;
+}
+
+/**
  * e_client_selector_is_backend_dead:
  * @selector: an #EClientSelector
  * @source: an #ESource
diff --git a/e-util/e-client-selector.h b/e-util/e-client-selector.h
index 8e3c1ac..ce91fe7 100644
--- a/e-util/e-client-selector.h
+++ b/e-util/e-client-selector.h
@@ -82,6 +82,9 @@ EClient *     e_client_selector_get_client_finish
 EClient *      e_client_selector_ref_cached_client
                                                (EClientSelector *selector,
                                                 ESource *source);
+EClient *      e_client_selector_ref_cached_client_by_iter
+                                               (EClientSelector *selector,
+                                                GtkTreeIter *iter);
 gboolean       e_client_selector_is_backend_dead
                                                (EClientSelector *selector,
                                                 ESource *source);