folks/presence-details.vala

   1 /*
   2  * Copyright (C) 2010-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  *       Travis Reitter <travis.reitter@collabora.co.uk>
  19  */
  20
  21 using GLib;
  22
  23 /**
  24  * The possible presence states an object implementing {@link PresenceDetails}
  25  * could be in.
  26  *
  27  * These closely follow the
  28  * [[http://telepathy.freedesktop.org/spec/Connection_Interface_Simple_Presence.html#Connection_Presence_Type|SimplePresence]]
  29  * interface in the Telepathy specification.
  30  */
  31 public enum Folks.PresenceType
  32 {
  33   /**
  34    * never set
  35    */
  36   UNSET,
  37   /**
  38    * offline
  39    */
  40   OFFLINE,
  41   /**
  42    * available
  43    */
  44   AVAILABLE,
  45   /**
  46    * away from keyboard
  47    */
  48   AWAY,
  49   /**
  50    * away from keyboard for an extended period of time
  51    */
  52   EXTENDED_AWAY,
  53   /**
  54    * also known as "invisible" or "appear offline"
  55    */
  56   HIDDEN,
  57   /**
  58    * at keyboard, but too busy to chat
  59    */
  60   BUSY,
  61   /**
  62    * presence not received from server
  63    */
  64   UNKNOWN,
  65   /**
  66    * an error occurred with fetching the presence
  67    */
  68   ERROR
  69 }
  70
  71 /**
  72  * Interface exposing a {@link Persona}'s or {@link Individual}'s presence;
  73  * their current availability, such as for chatting.
  74  *
  75  * If the {@link Backend} providing the {@link Persona} doesn't support
  76  * presence, the {@link Persona}'s `presence_type` will be set to
  77  * {@link PresenceType.UNSET} and their `presence_message` will be an empty
  78  * string.
  79  */
  80 public interface Folks.PresenceDetails : Object
  81 {
  82   /**
  83    * The contact's presence type.
  84    *
  85    * Each contact can have one and only one presence type at any one time,
  86    * representing their availability for communication. The default presence
  87    * type is {@link PresenceType.UNSET}.
  88    */
  89   public abstract Folks.PresenceType presence_type
  90     {
  91       get; set; default = Folks.PresenceType.UNSET;
  92     }
  93
  94   /**
  95    * The contact's presence message.
  96    *
  97    * This is a short message written by the contact to add detail to their
  98    * presence type ({@link Folks.PresenceDetails.presence_type}). If the contact
  99    * hasn't set a message, it will be an empty string.
 100    */
 101   public abstract string presence_message { get; set; default = ""; }
 102
 103   /**
 104    * The contact's detailed presence status.
 105    *
 106    * This is a more detailed representation of the contact's presence than
 107    * {@link PresenceDetails.presence_type}. It may be empty, or one of a
 108    * well-known set of strings, as defined in the Telepathy specification:
 109    * [[http://telepathy.freedesktop.org/spec/Connection_Interface_Simple_Presence.html#description|Telepathy Specification]]
 110    *
 111    * @since 0.6.0
 112    */
 113   public abstract string presence_status { get; set; default = ""; }
 114
 115   /* Rank the presence types for comparison purposes, with higher numbers
 116    * meaning more available */
 117   private static int _type_availability (PresenceType type)
 118     {
 119       switch (type)
 120         {
 121           case PresenceType.UNSET:
 122             return 0;
 123           case PresenceType.UNKNOWN:
 124             return 1;
 125           case PresenceType.ERROR:
 126             return 2;
 127           case PresenceType.OFFLINE:
 128             return 3;
 129           case PresenceType.HIDDEN:
 130             return 4;
 131           case PresenceType.EXTENDED_AWAY:
 132             return 5;
 133           case PresenceType.AWAY:
 134             return 6;
 135           case PresenceType.BUSY:
 136             return 7;
 137           case PresenceType.AVAILABLE:
 138             return 8;
 139           default:
 140             return 1;
 141         }
 142     }
 143
 144   /**
 145    * The default message for a presence type.
 146    *
 147    * @since UNRELEASED
 148    */
 149   public static string get_default_message_from_type (PresenceType type)
 150     {
 151       switch (type)
 152         {
 153           default:
 154           case PresenceType.UNKNOWN:
 155             return _("Unknown status");
 156           case PresenceType.OFFLINE:
 157             return _("Offline");
 158           case PresenceType.UNSET:
 159             return "";
 160           case PresenceType.ERROR:
 161             return _("Error");
 162           case PresenceType.AVAILABLE:
 163             return _("Available");
 164           case PresenceType.AWAY:
 165             return _("Away");
 166           case PresenceType.EXTENDED_AWAY:
 167             return _("Extended away");
 168           case PresenceType.BUSY:
 169             return _("Busy");
 170           case PresenceType.HIDDEN:
 171             return _("Hidden");
 172         }
 173     }
 174
 175   /**
 176    * Compare two {@link PresenceType}s.
 177    *
 178    * `0` will be returned if the types are equal, a positive number will be
 179    * returned if `type_a` is more available than `type_b`, and a negative
 180    * number will be returned if the opposite is true.
 181    *
 182    * @param type_a the first {@link PresenceType} to compare
 183    * @param type_b the second {@link PresenceType} to compare
 184    * @return a number representing the similarity of the two types
 185    * @since 0.1.11
 186    */
 187   public static int typecmp (PresenceType type_a, PresenceType type_b)
 188     {
 189       return (PresenceDetails._type_availability (type_a) -
 190           PresenceDetails._type_availability (type_b));
 191     }
 192
 193   /**
 194    * Whether the contact is online.
 195    *
 196    * This will be `true` if the contact's presence type is higher than
 197    * {@link PresenceType.OFFLINE}, as determined by
 198    * {@link PresenceDetails.typecmp}.
 199    *
 200    * @return `true` if the contact is online, `false` otherwise
 201    */
 202   public bool is_online ()
 203     {
 204       return (typecmp (this.presence_type, PresenceType.OFFLINE) > 0);
 205     }
 206 }