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 0.6.3
  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 0.6.3
  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 0.6.3
  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 0.6.3
  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, a non-empty URI
  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       if (value == "")
  90         {
  91           warning ("Empty URI passed to UrlFieldDetails.");
  92         }
  93
  94       Object (value: value,
  95               parameters: parameters);
  96     }
  97
  98   /**
  99    * {@inheritDoc}
 100    *
 101    * @since 0.6.0
 102    */
 103   public override bool equal (AbstractFieldDetails<string> that)
 104     {
 105       return base.equal (that);
 106     }
 107
 108   /**
 109    * {@inheritDoc}
 110    *
 111    * @since 0.6.0
 112    */
 113   public override uint hash ()
 114     {
 115       return base.hash ();
 116     }
 117 }
 118
 119 /**
 120  * Associates a list of URLs with a contact.
 121  *
 122  * @since 0.3.5
 123  */
 124 public interface Folks.UrlDetails : Object
 125 {
 126   /**
 127    * The websites of the contact.
 128    *
 129    * A list or websites associated to the contact.
 130    *
 131    * @since 0.5.1
 132    */
 133   public abstract Set<UrlFieldDetails> urls { get; set; }
 134
 135   /**
 136    * Change the contact's URLs.
 137    *
 138    * It's preferred to call this rather than setting {@link UrlDetails.urls}
 139    * directly, as this method gives error notification and will only return once
 140    * the URLs have been written to the relevant backing store (or the
 141    * operation's failed).
 142    *
 143    * @param urls the set of URLs
 144    * @throws PropertyError if setting the URLs failed
 145    * @since 0.6.2
 146    */
 147   public virtual async void change_urls (Set<UrlFieldDetails> urls)
 148       throws PropertyError
 149     {
 150       /* Default implementation. */
 151       throw new PropertyError.NOT_WRITEABLE (
 152           _("URLs are not writeable on this contact."));
 153     }
 154 }