Post-release version bump

[platform/upstream/folks.git] / folks / name-details.vala

diff --git a/folks/name-details.vala b/folks/name-details.vala
index ed808cc..dd35c59 100644 (file)
--- a/folks/name-details.vala
+++ b/folks/name-details.vala
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2011 Collabora Ltd.
+ * Copyright (C) 2011 Philip Withnall
  *
  * This library is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -17,6 +18,7 @@
  * Authors:
  *       Marco Barisione <marco.barisione@collabora.co.uk>
  *       Raul Gutierrez Segales <raul.gutierrez.segales@collabora.co.uk>
+ *       Philip Withnall <philip@tecnocode.co.uk>
  */
 
 using GLib;
@@ -167,6 +169,7 @@ public class Folks.StructuredName : Object
   /**
    * Whether two StructuredNames are the same.
    *
+   * @param other the other structured name to compare with
    * @return `true` if all the components are the same, `false`
    * otherwise.
    *
@@ -219,7 +222,27 @@ public interface Folks.NameDetails : Object
    *
    * @since 0.3.5
    */
-  public abstract StructuredName structured_name { get; set; }
+  public abstract StructuredName? structured_name { get; set; }
+
+  /**
+   * Change the contact's structured name.
+   *
+   * It's preferred to call this rather than setting
+   * {@link NameDetails.structured_name} directly, as this method gives error
+   * notification and will only return once the name has been written to the
+   * relevant backing store (or the operation's failed).
+   *
+   * @param name the structured name (`null` to unset it)
+   * @throws PropertyError if setting the structured name failed
+   * @since 0.6.2
+   */
+  public virtual async void change_structured_name (StructuredName? name)
+      throws PropertyError
+    {
+      /* Default implementation. */
+      throw new PropertyError.NOT_WRITEABLE (
+          _("Structured name is not writeable on this contact."));
+    }
 
   /**
    * The full name of the contact.
@@ -231,18 +254,68 @@ public interface Folks.NameDetails : Object
    * The full name could or could not contain additional names (like a
    * middle name), prefixes or suffixes.
    *
+   * The full name must not be `null`: the empty string represents an unset full
+   * name.
+   *
    * @since 0.3.5
    */
   public abstract string full_name { get; set; }
 
   /**
+   * Change the contact's full name.
+   *
+   * It's preferred to call this rather than setting
+   * {@link NameDetails.full_name} directly, as this method gives error
+   * notification and will only return once the name has been written to the
+   * relevant backing store (or the operation's failed).
+   *
+   * @param full_name the full name (empty string to unset it)
+   * @throws PropertyError if setting the full name failed
+   * @since 0.6.2
+   */
+  public virtual async void change_full_name (string full_name)
+      throws PropertyError
+    {
+      /* Default implementation. */
+      throw new PropertyError.NOT_WRITEABLE (
+          _("Full name is not writeable on this contact."));
+    }
+
+  /**
    * The nickname of the contact.
    *
    * The nickname is the name that the contact chose for himself. This is
    * different from {@link AliasDetails.alias} as aliases can be chosen by
    * the user and not by the contacts themselves.
    *
+   * Consequently, setting the nickname only makes sense in the context of an
+   * address book when updating the information a contact has specified about
+   * themselves.
+   *
+   * The nickname must not be `null`: the empty string represents an unset
+   * nickname.
+   *
    * @since 0.3.5
    */
-  public abstract string nickname { get; }
+  public abstract string nickname { get; set; }
+
+  /**
+   * Change the contact's nickname.
+   *
+   * It's preferred to call this rather than setting
+   * {@link NameDetails.nickname} directly, as this method gives error
+   * notification and will only return once the name has been written to the
+   * relevant backing store (or the operation's failed).
+   *
+   * @param nickname the nickname (empty string to unset it)
+   * @throws PropertyError if setting the nickname failed
+   * @since 0.6.2
+   */
+  public virtual async void change_nickname (string nickname)
+      throws PropertyError
+    {
+      /* Default implementation. */
+      throw new PropertyError.NOT_WRITEABLE (
+          _("Nickname is not writeable on this contact."));
+    }
 }