folks/role-details.vala

   1 /*
   2  * Copyright (C) 2011 Collabora Ltd.
   3  *
   4  * This library is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Authors:
  18  *       Raul Gutierrez Segales <raul.gutierrez.segales@collabora.co.uk>
  19  *       Travis Reitter <travis.reitter@collabora.co.uk>
  20  */
  21
  22 using Gee;
  23 using GLib;
  24
  25 /**
  26  * This interface represents the role a {@link Persona} and {@link Individual}
  27  * have in a given Organisation.
  28  *
  29  * @since 0.4.0
  30  */
  31 public class Folks.Role : Object
  32 {
  33   /**
  34    * The name of the organisation in which the role is held.
  35    */
  36   public string organisation_name { get; set; }
  37
  38   /**
  39    * The title of the position held.
  40    *
  41    * For example: “Director, Ministry of Silly Walks”
  42    */
  43   public string title { get; set; }
  44
  45   /**
  46    * The role of the position.
  47    *
  48    * For example: “Programmer”
  49    *
  50    * @since 0.6.0
  51    */
  52   public string role { get; set; }
  53
  54   /**
  55    * The UID that distinguishes this role.
  56    */
  57   public string uid { get; set; }
  58
  59   /**
  60    * Default constructor.
  61    *
  62    * @param title title of the position
  63    * @param organisation_name organisation where the role is hold
  64    * @param uid a Unique ID associated to this Role
  65    * @return a new Role
  66    *
  67    * @since 0.4.0
  68    */
  69   public Role (string? title = null,
  70       string? organisation_name = null, string? uid = null)
  71     {
  72       if (title == null)
  73         {
  74           title = "";
  75         }
  76
  77       if (organisation_name == null)
  78         {
  79           organisation_name = "";
  80         }
  81
  82       if (uid == null)
  83         {
  84           uid = "";
  85         }
  86
  87       Object (uid:                  uid,
  88               title:                title,
  89               organisation_name:    organisation_name);
  90     }
  91
  92   /**
  93    * Compare if two roles are equal. Roles are equal if their titles and
  94    * organisation names are equal.
  95    *
  96    * @param a a role to compare
  97    * @param b another role to compare
  98    * @return `true` if the roles are equal, `false` otherwise
  99    */
 100   public static bool equal (Role a, Role b)
 101     {
 102       return (a.title == b.title) &&
 103           (a.role == b.role) &&
 104           (a.organisation_name == b.organisation_name);
 105     }
 106
 107   /**
 108    * Hash function for the class. Suitable for use as a hash table key.
 109    *
 110    * @param r a role to hash
 111    * @return hash value for the role instance
 112    */
 113   public static uint hash (Role r)
 114     {
 115       return r.organisation_name.hash () ^ r.title.hash () ^ r.role.hash ();
 116     }
 117
 118   /**
 119    * Formatted version of this role.
 120    *
 121    * @since 0.4.0
 122    */
 123   public string to_string ()
 124     {
 125       var str = _("Title: %s, Organisation: %s, Role: %s");
 126       return str.printf (this.title, this.organisation_name, this.role);
 127     }
 128 }
 129
 130 /**
 131  * Object representing details of a contact in an organisation which can have
 132  * some parameters associated with it.
 133  *
 134  * See {@link Folks.AbstractFieldDetails}.
 135  *
 136  * @since 0.6.0
 137  */
 138 public class Folks.RoleFieldDetails : AbstractFieldDetails<Role>
 139 {
 140   /**
 141    * Create a new RoleFieldDetails.
 142    *
 143    * @param value the {@link Role} of the field
 144    * @param parameters initial parameters. See
 145    * {@link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
 146    * empty map of parameters.
 147    *
 148    * @return a new RoleFieldDetails
 149    *
 150    * @since 0.6.0
 151    */
 152   public RoleFieldDetails (Role value,
 153       MultiMap<string, string>? parameters = null)
 154     {
 155       this.value = value;
 156       if (parameters != null)
 157         this.parameters = parameters;
 158     }
 159
 160   /**
 161    * {@inheritDoc}
 162    *
 163    * @since 0.6.0
 164    */
 165   public override bool equal (AbstractFieldDetails<string> that)
 166     {
 167       var that_fd = that as RoleFieldDetails;
 168
 169       if (that_fd == null)
 170         return false;
 171
 172       return Role.equal (this.value, that_fd.value);
 173     }
 174
 175   /**
 176    * {@inheritDoc}
 177    *
 178    * @since 0.6.0
 179    */
 180   public override uint hash ()
 181     {
 182       return str_hash (this.value.to_string ());
 183     }
 184 }
 185
 186 /**
 187  * This interfaces represents the list of roles a {@link Persona} and
 188  * {@link Individual} might have.
 189  *
 190  * @since 0.4.0
 191  */
 192 public interface Folks.RoleDetails : Object
 193 {
 194   /**
 195    * The roles of the contact.
 196    *
 197    * @since 0.6.0
 198    */
 199   public abstract Set<RoleFieldDetails> roles { get; set; }
 200 }