folks/email-details.vala

   1 /*
   2  * Copyright (C) 2011 Collabora Ltd.
   3  * Copyright (C) 2011 Philip Withnall
   4  *
   5  * This library is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU Lesser General Public License as published by
   7  * the Free Software Foundation, either version 2.1 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public License
  16  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  17  *
  18  * Authors:
  19  *       Marco Barisione <marco.barisione@collabora.co.uk>
  20  *       Philip Withnall <philip@tecnocode.co.uk>
  21  */
  22
  23 using GLib;
  24 using Gee;
  25
  26 /**
  27  * Object representing a email address that can have some parameters
  28  * associated with it.
  29  *
  30  * See {@link Folks.AbstractFieldDetails} for details on common parameter names
  31  * and values.
  32  *
  33  * @since 0.6.0
  34  */
  35 public class Folks.EmailFieldDetails : AbstractFieldDetails<string>
  36 {
  37   /**
  38    * Create a new EmailFieldDetails.
  39    *
  40    * @param value the value of the field, which should be a valid, non-empty
  41    * e-mail address
  42    * @param parameters initial parameters. See
  43    * {@link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
  44    * empty map of parameters.
  45    *
  46    * @return a new EmailFieldDetails
  47    *
  48    * @since 0.6.0
  49    */
  50   public EmailFieldDetails (string value,
  51       MultiMap<string, string>? parameters = null)
  52     {
  53       if (value == "")
  54         {
  55           warning ("Empty e-mail address passed to EmailFieldDetails.");
  56         }
  57
  58       this.value = value;
  59       if (parameters != null)
  60         this.parameters = parameters;
  61     }
  62
  63   /**
  64    * {@inheritDoc}
  65    *
  66    * @since 0.6.0
  67    */
  68   public override bool equal (AbstractFieldDetails<string> that)
  69     {
  70       return base.equal<string> (that);
  71     }
  72
  73   /**
  74    * {@inheritDoc}
  75    *
  76    * @since 0.6.0
  77    */
  78   public override uint hash ()
  79     {
  80       return base.hash ();
  81     }
  82 }
  83
  84 /**
  85  * Interface for classes that have email addresses, such as {@link Persona}
  86  * and {@link Individual}.
  87  *
  88  * @since 0.3.5
  89  */
  90 public interface Folks.EmailDetails : Object
  91 {
  92   /**
  93    * The email addresses of the contact.
  94    *
  95    * Each of the values in this property contains just an e-mail address (e.g.
  96    * “foo@bar.com”), rather than any other way of formatting an e-mail address
  97    * (such as “John Smith <foo@bar.com>”).
  98    *
  99    * @since 0.6.0
 100    */
 101   public abstract Set<EmailFieldDetails> email_addresses { get; set; }
 102
 103   /**
 104    * Change the contact's set of e-mail addresses.
 105    *
 106    * It's preferred to call this rather than setting
 107    * {@link EmailDetails.email_addresses} directly, as this method gives error
 108    * notification and will only return once the e-mail addresses have been
 109    * written to the relevant backing store (or the operation's failed).
 110    *
 111    * @param email_addresses the new set of e-mail addresses
 112    * @throws PropertyError if setting the e-mail addresses failed
 113    * @since 0.6.2
 114    */
 115   public virtual async void change_email_addresses (
 116       Set<EmailFieldDetails> email_addresses) throws PropertyError
 117     {
 118       /* Default implementation. */
 119       throw new PropertyError.NOT_WRITEABLE (
 120           _("E-mail addresses are not writeable on this contact."));
 121     }
 122 }