libpurple/presence.h

   1 /*
   2  * purple
   3  *
   4  * Purple is the legal property of its developers, whose names are too numerous
   5  * to list here.  Please refer to the COPYRIGHT file distributed with this
   6  * source distribution.
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  21  */
  22
  23 #ifndef PURPLE_PRESENCE_H
  24 #define PURPLE_PRESENCE_H
  25 /**
  26  * SECTION:presence
  27  * @section_id: libpurple-presence
  28  * @short_description: <filename>presence.h</filename>
  29  * @title: Presence Objects API
  30  *
  31  * This file contains the presence base type, account presence, and buddy
  32  * presence API.
  33  */
  34
  35 /**
  36  * PurplePresence:
  37  *
  38  * A PurplePresence is like a collection of PurpleStatuses (plus some
  39  * other random info).  For any buddy, or for any one of your accounts,
  40  * or for any person with which you're chatting, you may know various
  41  * amounts of information.  This information is all contained in
  42  * one PurplePresence.  If one of your buddies is away and idle,
  43  * then the presence contains the PurpleStatus for their awayness,
  44  * and it contains their current idle time.  PurplePresences are
  45  * never saved to disk.  The information they contain is only relevant
  46  * for the current PurpleSession.
  47  *
  48  * Note: When a presence is destroyed with the last g_object_unref(), all
  49  *       statuses added to this list will be destroyed along with the presence.
  50  */
  51 typedef struct _PurplePresence PurplePresence;
  52
  53 #include "account.h"
  54 #include "buddylist.h"
  55 #include "status.h"
  56
  57 /**
  58  * PurplePresenceClass:
  59  * @update_idle: Updates the logs and the UI when the idle state or time of the
  60  *               presence changes.
  61  *
  62  * Base class for all #PurplePresence's
  63  */
  64 struct _PurplePresenceClass {
  65         GObjectClass parent_class;
  66
  67         void (*update_idle)(PurplePresence *presence, gboolean old_idle);
  68
  69         /*< private >*/
  70         void (*_purple_reserved1)(void);
  71         void (*_purple_reserved2)(void);
  72         void (*_purple_reserved3)(void);
  73         void (*_purple_reserved4)(void);
  74 };
  75
  76 G_BEGIN_DECLS
  77
  78 /**************************************************************************/
  79 /* PurplePresence API                                                     */
  80 /**************************************************************************/
  81
  82 #define PURPLE_TYPE_PRESENCE  purple_presence_get_type()
  83
  84 /**
  85  * purple_presence_get_type:
  86  *
  87  * Returns: The #GType for the #PurplePresence object.
  88  */
  89 G_DECLARE_DERIVABLE_TYPE(PurplePresence, purple_presence, PURPLE,
  90                 PRESENCE, GObject)
  91
  92 /**
  93  * purple_presence_set_status_active:
  94  * @presence:  The presence.
  95  * @status_id: The ID of the status.
  96  * @active:    The active state.
  97  *
  98  * Sets the active state of a status in a presence.
  99  *
 100  * Only independent statuses can be set unactive. Normal statuses can only
 101  * be set active, so if you wish to disable a status, set another
 102  * non-independent status to active, or use purple_presence_switch_status().
 103  */
 104 void purple_presence_set_status_active(PurplePresence *presence,
 105                                                                          const char *status_id, gboolean active);
 106
 107 /**
 108  * purple_presence_switch_status:
 109  * @presence: The presence.
 110  * @status_id: The status ID to switch to.
 111  *
 112  * Switches the active status in a presence.
 113  *
 114  * This is similar to purple_presence_set_status_active(), except it won't
 115  * activate independent statuses.
 116  */
 117 void purple_presence_switch_status(PurplePresence *presence,
 118                                                                  const char *status_id);
 119
 120 /**
 121  * purple_presence_set_idle:
 122  * @presence:  The presence.
 123  * @idle:      The idle state.
 124  * @idle_time: The idle time, if @idle is TRUE.  This
 125  *                  is the time at which the user became idle,
 126  *                  in seconds since the epoch.  If this value is
 127  *                  unknown then 0 should be used.
 128  *
 129  * Sets the idle state and time on a presence.
 130  */
 131 void purple_presence_set_idle(PurplePresence *presence, gboolean idle,
 132                                                         time_t idle_time);
 133
 134 /**
 135  * purple_presence_set_login_time:
 136  * @presence:   The presence.
 137  * @login_time: The login time.
 138  *
 139  * Sets the login time on a presence.
 140  */
 141 void purple_presence_set_login_time(PurplePresence *presence, time_t login_time);
 142
 143 /**
 144  * purple_presence_get_statuses:
 145  * @presence: The presence.
 146  *
 147  * Returns all the statuses in a presence.
 148  *
 149  * Returns: (element-type PurpleStatus) (transfer none): The statuses.
 150  */
 151 GList *purple_presence_get_statuses(PurplePresence *presence);
 152
 153 /**
 154  * purple_presence_get_status:
 155  * @presence:  The presence.
 156  * @status_id: The ID of the status.
 157  *
 158  * Returns the status with the specified ID from a presence.
 159  *
 160  * Returns: (transfer none): The status if found, or %NULL.
 161  */
 162 PurpleStatus *purple_presence_get_status(PurplePresence *presence,
 163                                                                          const char *status_id);
 164
 165 /**
 166  * purple_presence_get_active_status:
 167  * @presence: The presence.
 168  *
 169  * Returns the active exclusive status from a presence.
 170  *
 171  * Returns: (transfer none): The active exclusive status.
 172  */
 173 PurpleStatus *purple_presence_get_active_status(PurplePresence *presence);
 174
 175 /**
 176  * purple_presence_is_available:
 177  * @presence: The presence.
 178  *
 179  * Returns whether or not a presence is available.
 180  *
 181  * Available presences are online and possibly invisible, but not away or idle.
 182  *
 183  * Returns: TRUE if the presence is available, or FALSE otherwise.
 184  */
 185 gboolean purple_presence_is_available(PurplePresence *presence);
 186
 187 /**
 188  * purple_presence_is_online:
 189  * @presence: The presence.
 190  *
 191  * Returns whether or not a presence is online.
 192  *
 193  * Returns: TRUE if the presence is online, or FALSE otherwise.
 194  */
 195 gboolean purple_presence_is_online(PurplePresence *presence);
 196
 197 /**
 198  * purple_presence_is_status_active:
 199  * @presence:  The presence.
 200  * @status_id: The ID of the status.
 201  *
 202  * Returns whether or not a status in a presence is active.
 203  *
 204  * A status is active if itself or any of its sub-statuses are active.
 205  *
 206  * Returns: TRUE if the status is active, or FALSE.
 207  */
 208 gboolean purple_presence_is_status_active(PurplePresence *presence,
 209                                                                                 const char *status_id);
 210
 211 /**
 212  * purple_presence_is_status_primitive_active:
 213  * @presence:  The presence.
 214  * @primitive: The status primitive.
 215  *
 216  * Returns whether or not a status with the specified primitive type
 217  * in a presence is active.
 218  *
 219  * A status is active if itself or any of its sub-statuses are active.
 220  *
 221  * Returns: TRUE if the status is active, or FALSE.
 222  */
 223 gboolean purple_presence_is_status_primitive_active(
 224         PurplePresence *presence, PurpleStatusPrimitive primitive);
 225
 226 /**
 227  * purple_presence_is_idle:
 228  * @presence: The presence.
 229  *
 230  * Returns whether or not a presence is idle.
 231  *
 232  * Returns: TRUE if the presence is idle, or FALSE otherwise.
 233  *         If the presence is offline (purple_presence_is_online()
 234  *         returns FALSE) then FALSE is returned.
 235  */
 236 gboolean purple_presence_is_idle(PurplePresence *presence);
 237
 238 /**
 239  * purple_presence_get_idle_time:
 240  * @presence: The presence.
 241  *
 242  * Returns the presence's idle time.
 243  *
 244  * Returns: The presence's idle time.
 245  */
 246 time_t purple_presence_get_idle_time(PurplePresence *presence);
 247
 248 /**
 249  * purple_presence_get_login_time:
 250  * @presence: The presence.
 251  *
 252  * Returns the presence's login time.
 253  *
 254  * Returns: The presence's login time.
 255  */
 256 time_t purple_presence_get_login_time(PurplePresence *presence);
 257
 258 /**************************************************************************/
 259 /* PurpleAccountPresence API                                              */
 260 /**************************************************************************/
 261
 262 #define PURPLE_TYPE_ACCOUNT_PRESENCE (purple_account_presence_get_type())
 263
 264 /**
 265  * purple_account_presence_get_type:
 266  *
 267  * Returns: The #GType for the #PurpleAccountPresence object.
 268  */
 269 G_DECLARE_FINAL_TYPE(PurpleAccountPresence, purple_account_presence,
 270                 PURPLE, ACCOUNT_PRESENCE, PurplePresence)
 271
 272 /**
 273  * purple_account_presence_new:
 274  * @account: The account to associate with the presence.
 275  *
 276  * Creates a presence for an account.
 277  *
 278  * Returns: The new presence.
 279  */
 280 PurpleAccountPresence *purple_account_presence_new(PurpleAccount *account);
 281
 282 /**
 283  * purple_account_presence_get_account:
 284  * @presence: The presence.
 285  *
 286  * Returns an account presence's account.
 287  *
 288  * Returns: (transfer none): The presence's account.
 289  */
 290 PurpleAccount *purple_account_presence_get_account(PurpleAccountPresence *presence);
 291
 292 /**************************************************************************/
 293 /* PurpleBuddyPresence API                                                */
 294 /**************************************************************************/
 295
 296 #define PURPLE_TYPE_BUDDY_PRESENCE (purple_buddy_presence_get_type())
 297
 298 /**
 299  * purple_buddy_presence_get_type:
 300  *
 301  * Returns: The #GType for the #PurpleBuddyPresence object.
 302  */
 303 G_DECLARE_FINAL_TYPE(PurpleBuddyPresence, purple_buddy_presence, PURPLE,
 304                 BUDDY_PRESENCE, PurplePresence)
 305
 306 /**
 307  * purple_buddy_presence_new:
 308  * @buddy: The buddy to associate with the presence.
 309  *
 310  * Creates a presence for a buddy.
 311  *
 312  * Returns: The new presence.
 313  */
 314 PurpleBuddyPresence *purple_buddy_presence_new(PurpleBuddy *buddy);
 315
 316 /**
 317  * purple_buddy_presence_get_buddy:
 318  * @presence: The presence.
 319  *
 320  * Returns the buddy presence's buddy.
 321  *
 322  * Returns: (transfer none): The presence's buddy.
 323  */
 324 PurpleBuddy *purple_buddy_presence_get_buddy(PurpleBuddyPresence *presence);
 325
 326 /**
 327  * purple_buddy_presence_compare:
 328  * @buddy_presence1: The first presence.
 329  * @buddy_presence2: The second presence.
 330  *
 331  * Compares two buddy presences for availability.
 332  *
 333  * Returns: -1 if @buddy_presence1 is more available than @buddy_presence2.
 334  *           0 if @buddy_presence1 is equal to @buddy_presence2.
 335  *           1 if @buddy_presence1 is less available than @buddy_presence2.
 336  */
 337 gint purple_buddy_presence_compare(PurpleBuddyPresence *buddy_presence1,
 338                                                    PurpleBuddyPresence *buddy_presence2);
 339
 340 G_END_DECLS
 341
 342 #endif /* PURPLE_PRESENCE_H */