folks/url-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  *       Travis Reitter <travis.reitter@collabora.co.uk>
  21  *       Philip Withnall <philip@tecnocode.co.uk>
  22  */
  23
  24 using GLib;
  25 using Gee;
  26
  27 /**
  28  * Object representing a URL that can have some parameters 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.UrlFieldDetails : AbstractFieldDetails<string>
  36 {
  37   /**
  38    * Parameter value for URLs for the contact's home page.
  39    *
  40    * Value for a parameter with name {@link AbstractFieldDetails.PARAM_TYPE}.
  41    *
  42    * @since UNRELEASED
  43    */
  44   public static const string PARAM_TYPE_HOME_PAGE = "x-home-page";
  45
  46   /**
  47    * Parameter value for URLs for the contact's personal or professional blog.
  48    *
  49    * Value for a parameter with name {@link AbstractFieldDetails.PARAM_TYPE}.
  50    *
  51    * @since UNRELEASED
  52    */
  53   public static const string PARAM_TYPE_BLOG = "x-blog";
  54
  55   /**
  56    * Parameter value for URLs for the contact's social networking profile.
  57    *
  58    * Value for a parameter with name {@link AbstractFieldDetails.PARAM_TYPE}.
  59    *
  60    * @since UNRELEASED
  61    */
  62   public static const string PARAM_TYPE_PROFILE = "x-profile";
  63
  64   /**
  65    * Parameter value for URLs for the contact's personal or professional FTP
  66    * server.
  67    *
  68    * Value for a parameter with name {@link AbstractFieldDetails.PARAM_TYPE}.
  69    *
  70    * @since UNRELEASED
  71    */
  72   public static const string PARAM_TYPE_FTP = "x-ftp";
  73
  74   /**
  75    * Create a new UrlFieldDetails.
  76    *
  77    * @param value the value of the field
  78    * @param parameters initial parameters. See
  79    * {@link AbstractFieldDetails.parameters}. A `null` value is equivalent to a
  80    * empty map of parameters.
  81    *
  82    * @return a new UrlFieldDetails
  83    *
  84    * @since 0.6.0
  85    */
  86   public UrlFieldDetails (string value,
  87       MultiMap<string, string>? parameters = null)
  88     {
  89       this.value = value;
  90       if (parameters != null)
  91         this.parameters = parameters;
  92     }
  93
  94   /**
  95    * {@inheritDoc}
  96    *
  97    * @since 0.6.0
  98    */
  99   public override bool equal (AbstractFieldDetails<string> that)
 100     {
 101       return base.equal<string> (that);
 102     }
 103
 104   /**
 105    * {@inheritDoc}
 106    *
 107    * @since 0.6.0
 108    */
 109   public override uint hash ()
 110     {
 111       return base.hash ();
 112     }
 113 }
 114
 115 /**
 116  * Associates a list of URLs with a contact.
 117  *
 118  * @since 0.3.5
 119  */
 120 public interface Folks.UrlDetails : Object
 121 {
 122   /**
 123    * The websites of the contact.
 124    *
 125    * A list or websites associated to the contact.
 126    *
 127    * @since 0.5.1
 128    */
 129   public abstract Set<UrlFieldDetails> urls { get; set; }
 130
 131   /**
 132    * Change the contact's URLs.
 133    *
 134    * It's preferred to call this rather than setting {@link UrlDetails.urls}
 135    * directly, as this method gives error notification and will only return once
 136    * the URLs have been written to the relevant backing store (or the
 137    * operation's failed).
 138    *
 139    * @param urls the set of URLs
 140    * @throws PropertyError if setting the URLs failed
 141    * @since 0.6.2
 142    */
 143   public virtual async void change_urls (Set<UrlFieldDetails> urls)
 144       throws PropertyError
 145     {
 146       /* Default implementation. */
 147       throw new PropertyError.NOT_WRITEABLE (
 148           _("URLs are not writeable on this contact."));
 149     }
 150 }