Post-release version bump

[platform/upstream/folks.git] / folks / persona.vala

diff --git a/folks/persona.vala b/folks/persona.vala
index f8a3fa5..75970fd 100644 (file)
--- a/folks/persona.vala
+++ b/folks/persona.vala
@@ -21,6 +21,37 @@
 using GLib;
 
 /**
+ * Errors which can be thrown when asynchronously setting a property of a
+ * {@link Persona} using a setter method defined on an interface such as
+ * {@link AliasDetails}.
+ *
+ * @since 0.6.2
+ */
+public errordomain Folks.PropertyError
+{
+  /**
+   * Property is not writeable for this particular object.
+   *
+   * @since 0.6.2
+   */
+  NOT_WRITEABLE,
+
+  /**
+   * Value was invalid for the property.
+   *
+   * @since 0.6.2
+   */
+  INVALID_VALUE,
+
+  /**
+   * Unknown error when setting the property.
+   *
+   * @since 0.6.2
+   */
+  UNKNOWN_ERROR
+}
+
+/**
  * Represents a "shard" of a person from a single source (a single
  * {@link Backend}), such as an XMPP contact from Telepathy or a vCard contact
  * from evolution-data-server.
@@ -30,6 +61,8 @@ using GLib;
  */
 public abstract class Folks.Persona : Object
 {
+  private weak Individual? _individual;
+
   /**
    * The internal ID used to represent the Persona for linking.
    *
@@ -52,6 +85,11 @@ public abstract class Folks.Persona : Object
    * This is the canonical way to refer to any Persona. It is guaranteed to be
    * unique within the Persona's {@link PersonaStore}.
    *
+   * A Persona's UID is immutable over the life of the Persona in the backing
+   * store, so a given UID is guaranteed to refer to the same Persona each time
+   * libfolks is used, until the Persona is permanently removed from its backing
+   * store.
+   *
    * @see Persona.build_uid
    * @see Persona.split_uid
    */
@@ -100,6 +138,33 @@ public abstract class Folks.Persona : Object
   public weak PersonaStore store { get; construct; }
 
   /**
+   * The {@link Individual} which contains this Persona.
+   *
+   * This may be `null`, but should only ever be so when the Persona has just
+   * been created, when its {@link PersonaStore} is being destroyed, or when
+   * it's moving between {@link Individual}s.
+   *
+   * @since 0.6.0
+   */
+  public weak Individual? individual
+    {
+      get
+        {
+          assert (this._individual == null ||
+              ((!) this._individual).personas.contains (this));
+
+          return this._individual;
+        }
+
+      internal set
+        {
+          assert (value == null || ((!) value).personas.contains (this));
+
+          this._individual = value;
+        }
+    }
+
+  /**
    * The names of the properties of this Persona which are linkable.
    *
    * If a property name is in this list, and the Persona is from a
@@ -114,11 +179,29 @@ public abstract class Folks.Persona : Object
    * This list will have no effect if the Persona's {@link PersonaStore} trust
    * level is not {@link PersonaStoreTrust.FULL}.
    *
+   * This property value is guaranteed to be constant for a given persona,
+   * but may vary between personas in the same store.
+   *
    * @since 0.1.13
    */
   public abstract string[] linkable_properties { get; }
 
   /**
+   * The names of the properties of this Persona which are writeable.
+   *
+   * If a property name is in this list, setting the property should result in
+   * the updated value being stored in the backend's permanent storage (unless
+   * it gets rejected due to being invalid, or a different error occurs).
+   *
+   * It's intended that this property value will be constant for a given Persona
+   * subclass, but this isn't guaranteed; it's possible that Persona subclasses
+   * may vary the value of this property at run time.
+   *
+   * @since 0.6.0
+   */
+  public abstract string[] writeable_properties { get; }
+
+  /**
    * Callback into the aggregator to manipulate a link mapping.
    *
    * This is a callback provided by the {@link IndividualAggregator} whenever