[folks] Bug 658576 â Need API to get a FolksIndividual from his ID

[Philip Withnall <pwithnall src gnome org>]

commit c46ccee525d63ad247e6ed552b946b39867c45a8
Author: Philip Withnall <philip tecnocode co uk>
Date:   Wed Mar 28 14:46:34 2012 +0100

    Bug 658576 â Need API to get a FolksIndividual from his ID
    
    Add an IndividualAggregator.look_up_individual() method which currently just
    looks up in the map from IDs to individuals. In future, however, this method
    will also ensure all properties of that individual have been loaded if the
    aggregator has otherwise not lazy-loaded properties. (See: bgo#648805.)
    
    Closes: https://bugzilla.gnome.org/show_bug.cgi?id=658576

 NEWS                             |    9 +++++++++
 folks/individual-aggregator.vala |   29 +++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 0 deletions(-)
---
diff --git a/NEWS b/NEWS
index 6d89c74..febb240 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,12 @@
+Overview of changes from libfolks 0.6.9 to libfolks 0.7.0
+=========================================================
+
+Bugs fixed:
+â Bug 658576 â Need API to get a FolksIndividual from his ID
+
+API changes:
+â Add IndividualAggregator.look_up_individual()
+
 Overview of changes from libfolks 0.6.8 to libfolks 0.6.9
 =============================================================
 
diff --git a/folks/individual-aggregator.vala b/folks/individual-aggregator.vala
index f0f567b..1100a0c 100644
--- a/folks/individual-aggregator.vala
+++ b/folks/individual-aggregator.vala
@@ -2012,4 +2012,33 @@ public class Folks.IndividualAggregator : Object
 
       return (!) new_persona;
     }
+
+  /**
+   * Look up an individual in the aggregator.
+   *
+   * This returns the { link Individual} with the given `id` if it exists in
+   * the aggregator, and `null` otherwise.
+   *
+   * In future, when lazy-loading of individuals' properties is added to folks,
+   * this method guarantees to load all properties of the individual, even if
+   * the aggregator hasn't lazy-loaded anything else.
+   *
+   * This method is safe to call before { link IndividualAggregator.prepare} has
+   * been called, and will call { link IndividualAggregator.prepare} itself in
+   * that case.
+   *
+   * @param id ID of the individual to look up
+   * @return individual with `id`, or `null` if no such individual was found
+   * @throws GLib.Error from { link IndividualAggregator.prepare}
+   *
+   * @since UNRELEASED
+   */
+  public async Individual? look_up_individual (string id) throws GLib.Error
+    {
+      /* Ensure the aggregator's prepared. */
+      yield this.prepare ();
+
+      /* FIXME: When bgo#648805 is fixed, this needs to support lazy-loading. */
+      return this._individuals.get (id);
+    }
 }