[folks] Helpers to check add_persona_from_details' compliance with basic attributes.

[Raul Gutierrez Segales <raulgs src gnome org>]

commit e198a0cd1e9717e711c32f8a4503c66a0768e82e
Author: Raul Gutierrez Segales <raul gutierrez segales collabora co uk>
Date:   Mon Mar 28 18:52:08 2011 +0100

    Helpers to check add_persona_from_details' compliance with basic attributes.
    
    The detail_key () method (along with the PersonaDetail enum) allows
    us to easily check the default attributes that should be handled
    in the HashTable received by add_persona_from_details.

 NEWS                     |    4 ++
 folks/persona-store.vala |   73 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 2 deletions(-)
---
diff --git a/NEWS b/NEWS
index 2bfed89..718d6f0 100644
--- a/NEWS
+++ b/NEWS
@@ -14,9 +14,13 @@ Bugs fixed:
 * Bug 645680 â?? Use random integer IDs for Kf.Personas
 * Bug 645475 â?? Linker warnings for Tracker backend tests
 * Bug 645570 â?? Fix checks for empty and equal StructuredNames
+* Bug 645989 â?? Ensure add_persona_from_details handles the basic attribute
 
 API changes:
 * Add equal () to StructuredName
+* Add detail_key () along with an enum PersonaDetail to PersonaStore
+  which together define the basic attributes that should be supported
+  by add_persona_from_details ().
 
 Overview of changes from libfolks 0.3.6 to libfolks 0.4.0
 =========================================================
diff --git a/folks/persona-store.vala b/folks/persona-store.vala
index c2b1add..fe16279 100644
--- a/folks/persona-store.vala
+++ b/folks/persona-store.vala
@@ -101,6 +101,30 @@ public errordomain Folks.PersonaStoreError
 }
 
 /**
+ * Definition of the available fields to be looked up with
+ * { link PersonaStore.detail_key}.
+ *
+ * @since UNRELEASED
+ */
+public enum Folks.PersonaDetail
+{
+  ALIAS,
+  FULL_NAME,
+  FAVOURITE,
+  STRUCTURED_NAME,
+  AVATAR,
+  BIRTHDAY,
+  GENDER,
+  EMAIL_ADDRESSES,
+  IM_ADDRESSES,
+  NOTES,
+  PHONE_NUMBERS,
+  POSTAL_ADDRESSES,
+  ROLES,
+  URLS
+}
+
+/**
  * A store for { link Persona}s.
  *
  * After creating a PersonaStore instance, you must connect to the
@@ -112,6 +136,49 @@ public errordomain Folks.PersonaStoreError
 public abstract class Folks.PersonaStore : Object
 {
   /**
+   * The following list of properties are the basic keys
+   * that each PersonaStore with write capabilities should
+   * support for { link Persona.add_persona_from_details}.
+   *
+   * Note that these aren't the only valid keys; backends are
+   * allowed to support keys beyond the ones defined here
+   * which might be specific to the backend in question.
+   *
+   * Should be kept in sync with { link Folks.PersonaDetail}.
+   *
+   * @since UNRELEASED
+   */
+  private static const string _PERSONA_DETAIL[] = {
+    "alias",
+    "full-name",
+    "is-favourite",
+    "structured-name",
+    "avatar",
+    "birthday",
+    "gender",
+    "email-addresses",
+    "im-addresses",
+    "notes",
+    "phone-numbers",
+    "postal-addresses",
+    "roles",
+    "urls"
+  };
+
+  /**
+   * Returns the key corresponding to @detail, for use in
+   * the details param of { link Persona.add_persona_from_details}.
+   *
+   * @param detail the { link PersonaDetail} to lookup
+   *
+   * @since UNRELEASED
+   */
+  public unowned string detail_key (Folks.PersonaDetail detail)
+    {
+      return this._PERSONA_DETAIL[detail];
+    }
+
+ /**
    * Emitted when one or more { link Persona}s are added to or removed from
    * the store.
    *
@@ -298,7 +365,7 @@ public abstract class Folks.PersonaStore : Object
    * Add a new { link Persona} to the PersonaStore.
    *
    * The { link Persona} will be created by the PersonaStore backend from the
-   * key-value pairs given in `details`. FIXME: These are backend-specific.
+   * key-value pairs given in `details`.
    *
    * All additions through this function will later be emitted through the
    * personas-changed signal to be notified of the new { link Persona}. The
@@ -311,7 +378,9 @@ public abstract class Folks.PersonaStore : Object
    * offline adds work.
    *
    * If the details are not recognised or are invalid,
-   * { link PersonaStoreError.INVALID_ARGUMENT} will be thrown.
+   * { link PersonaStoreError.INVALID_ARGUMENT} will be thrown. A default set
+   * of possible details are defined by { link Folks.PersonaDetail} but backends
+   * can either support a subset or superset of the suggested defaults.
    *
    * If a { link Persona} with the given details already exists in the store, no
    * error will be thrown and this function will return `null`.