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 #define PURPLE_TYPE_PRESENCE             (purple_presence_get_type())
  36 #define PURPLE_PRESENCE(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_PRESENCE, PurplePresence))
  37 #define PURPLE_PRESENCE_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_PRESENCE, PurplePresenceClass))
  38 #define PURPLE_IS_PRESENCE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PRESENCE))
  39 #define PURPLE_IS_PRESENCE_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_PRESENCE))
  40 #define PURPLE_PRESENCE_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_PRESENCE, PurplePresenceClass))
  41
  42 typedef struct _PurplePresence  PurplePresence;
  43 typedef struct _PurplePresenceClass  PurplePresenceClass;
  44
  45 #define PURPLE_TYPE_ACCOUNT_PRESENCE             (purple_account_presence_get_type())
  46 #define PURPLE_ACCOUNT_PRESENCE(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_ACCOUNT_PRESENCE, PurpleAccountPresence))
  47 #define PURPLE_ACCOUNT_PRESENCE_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_ACCOUNT_PRESENCE, PurpleAccountPresenceClass))
  48 #define PURPLE_IS_ACCOUNT_PRESENCE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_ACCOUNT_PRESENCE))
  49 #define PURPLE_IS_ACCOUNT_PRESENCE_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_ACCOUNT_PRESENCE))
  50 #define PURPLE_ACCOUNT_PRESENCE_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_ACCOUNT_PRESENCE, PurpleAccountPresenceClass))
  51
  52 typedef struct _PurpleAccountPresence  PurpleAccountPresence;
  53 typedef struct _PurpleAccountPresenceClass  PurpleAccountPresenceClass;
  54
  55 #define PURPLE_TYPE_BUDDY_PRESENCE             (purple_buddy_presence_get_type())
  56 #define PURPLE_BUDDY_PRESENCE(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_BUDDY_PRESENCE, PurpleBuddyPresence))
  57 #define PURPLE_BUDDY_PRESENCE_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_BUDDY_PRESENCE, PurpleBuddyPresenceClass))
  58 #define PURPLE_IS_BUDDY_PRESENCE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_BUDDY_PRESENCE))
  59 #define PURPLE_IS_BUDDY_PRESENCE_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_BUDDY_PRESENCE))
  60 #define PURPLE_BUDDY_PRESENCE_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_BUDDY_PRESENCE, PurpleBuddyPresenceClass))
  61
  62 typedef struct _PurpleBuddyPresence  PurpleBuddyPresence;
  63 typedef struct _PurpleBuddyPresenceClass  PurpleBuddyPresenceClass;
  64
  65 #include "account.h"
  66 #include "buddylist.h"
  67 #include "status.h"
  68
  69 /**
  70  * PurplePresence:
  71  *
  72  * A PurplePresence is like a collection of PurpleStatuses (plus some
  73  * other random info).  For any buddy, or for any one of your accounts,
  74  * or for any person with which you're chatting, you may know various
  75  * amounts of information.  This information is all contained in
  76  * one PurplePresence.  If one of your buddies is away and idle,
  77  * then the presence contains the PurpleStatus for their awayness,
  78  * and it contains their current idle time.  PurplePresences are
  79  * never saved to disk.  The information they contain is only relevant
  80  * for the current PurpleSession.
  81  *
  82  * Note: When a presence is destroyed with the last g_object_unref(), all
  83  *       statuses added to this list will be destroyed along with the presence.
  84  */
  85 struct _PurplePresence
  86 {
  87         GObject gparent;
  88 };
  89
  90 /**
  91  * PurplePresenceClass:
  92  * @update_idle: Updates the logs and the UI when the idle state or time of the
  93  *               presence changes.
  94  *
  95  * Base class for all #PurplePresence's
  96  */
  97 struct _PurplePresenceClass {
  98         GObjectClass parent_class;
  99
 100         void (*update_idle)(PurplePresence *presence, gboolean old_idle);
 101
 102         /*< private >*/
 103         void (*_purple_reserved1)(void);
 104         void (*_purple_reserved2)(void);
 105         void (*_purple_reserved3)(void);
 106         void (*_purple_reserved4)(void);
 107 };
 108
 109 /**
 110  * PurpleAccountPresence:
 111  *
 112  * A presence for an account
 113  */
 114 struct _PurpleAccountPresence
 115 {
 116         PurplePresence parent;
 117 };
 118
 119 /**
 120  * PurpleAccountPresenceClass:
 121  *
 122  * Base class for all #PurpleAccountPresence's
 123  */
 124 struct _PurpleAccountPresenceClass {
 125         PurplePresenceClass parent_class;
 126
 127         /*< private >*/
 128         void (*_purple_reserved1)(void);
 129         void (*_purple_reserved2)(void);
 130         void (*_purple_reserved3)(void);
 131         void (*_purple_reserved4)(void);
 132 };
 133
 134 /**
 135  * PurpleBuddyPresence:
 136  *
 137  * A presence for a buddy
 138  */
 139 struct _PurpleBuddyPresence
 140 {
 141         PurplePresence parent;
 142 };
 143
 144 /**
 145  * PurpleBuddyPresenceClass:
 146  *
 147  * Base class for all #PurpleBuddyPresence's
 148  */
 149 struct _PurpleBuddyPresenceClass {
 150         PurplePresenceClass parent_class;
 151
 152         /*< private >*/
 153         void (*_purple_reserved1)(void);
 154         void (*_purple_reserved2)(void);
 155         void (*_purple_reserved3)(void);
 156         void (*_purple_reserved4)(void);
 157 };
 158
 159 G_BEGIN_DECLS
 160
 161 /**************************************************************************/
 162 /* PurpleAccountPresence API                                              */
 163 /**************************************************************************/
 164
 165 /**
 166  * purple_account_presence_get_type:
 167  *
 168  * Returns: The #GType for the #PurpleAccountPresence object.
 169  */
 170 GType purple_account_presence_get_type(void);
 171
 172 /**
 173  * purple_account_presence_new:
 174  * @account: The account to associate with the presence.
 175  *
 176  * Creates a presence for an account.
 177  *
 178  * Returns: The new presence.
 179  */
 180 PurpleAccountPresence *purple_account_presence_new(PurpleAccount *account);
 181
 182 /**
 183  * purple_account_presence_get_account:
 184  * @presence: The presence.
 185  *
 186  * Returns an account presence's account.
 187  *
 188  * Returns: The presence's account.
 189  */
 190 PurpleAccount *purple_account_presence_get_account(const PurpleAccountPresence *presence);
 191
 192 /**************************************************************************/
 193 /* PurpleBuddyPresence API                                                */
 194 /**************************************************************************/
 195
 196 /**
 197  * purple_buddy_presence_get_type:
 198  *
 199  * Returns: The #GType for the #PurpleBuddyPresence object.
 200  */
 201 GType purple_buddy_presence_get_type(void);
 202
 203 /**
 204  * purple_buddy_presence_new:
 205  * @buddy: The buddy to associate with the presence.
 206  *
 207  * Creates a presence for a buddy.
 208  *
 209  * Returns: The new presence.
 210  */
 211 PurpleBuddyPresence *purple_buddy_presence_new(PurpleBuddy *buddy);
 212
 213 /**
 214  * purple_buddy_presence_get_buddy:
 215  * @presence: The presence.
 216  *
 217  * Returns the buddy presence's buddy.
 218  *
 219  * Returns: The presence's buddy.
 220  */
 221 PurpleBuddy *purple_buddy_presence_get_buddy(const PurpleBuddyPresence *presence);
 222
 223 /**
 224  * purple_buddy_presence_compare:
 225  * @buddy_presence1: The first presence.
 226  * @buddy_presence2: The second presence.
 227  *
 228  * Compares two buddy presences for availability.
 229  *
 230  * Returns: -1 if @buddy_presence1 is more available than @buddy_presence2.
 231  *           0 if @buddy_presence1 is equal to @buddy_presence2.
 232  *           1 if @buddy_presence1 is less available than @buddy_presence2.
 233  */
 234 gint purple_buddy_presence_compare(const PurpleBuddyPresence *buddy_presence1,
 235                                                    const PurpleBuddyPresence *buddy_presence2);
 236
 237 /**************************************************************************/
 238 /* PurplePresence API                                                     */
 239 /**************************************************************************/
 240
 241 /**
 242  * purple_presence_get_type:
 243  *
 244  * Returns: The #GType for the #PurplePresence object.
 245  */
 246 GType purple_presence_get_type(void);
 247
 248 /**
 249  * purple_presence_set_status_active:
 250  * @presence:  The presence.
 251  * @status_id: The ID of the status.
 252  * @active:    The active state.
 253  *
 254  * Sets the active state of a status in a presence.
 255  *
 256  * Only independent statuses can be set unactive. Normal statuses can only
 257  * be set active, so if you wish to disable a status, set another
 258  * non-independent status to active, or use purple_presence_switch_status().
 259  */
 260 void purple_presence_set_status_active(PurplePresence *presence,
 261                                                                          const char *status_id, gboolean active);
 262
 263 /**
 264  * purple_presence_switch_status:
 265  * @presence: The presence.
 266  * @status_id: The status ID to switch to.
 267  *
 268  * Switches the active status in a presence.
 269  *
 270  * This is similar to purple_presence_set_status_active(), except it won't
 271  * activate independent statuses.
 272  */
 273 void purple_presence_switch_status(PurplePresence *presence,
 274                                                                  const char *status_id);
 275
 276 /**
 277  * purple_presence_set_idle:
 278  * @presence:  The presence.
 279  * @idle:      The idle state.
 280  * @idle_time: The idle time, if @idle is TRUE.  This
 281  *                  is the time at which the user became idle,
 282  *                  in seconds since the epoch.  If this value is
 283  *                  unknown then 0 should be used.
 284  *
 285  * Sets the idle state and time on a presence.
 286  */
 287 void purple_presence_set_idle(PurplePresence *presence, gboolean idle,
 288                                                         time_t idle_time);
 289
 290 /**
 291  * purple_presence_set_login_time:
 292  * @presence:   The presence.
 293  * @login_time: The login time.
 294  *
 295  * Sets the login time on a presence.
 296  */
 297 void purple_presence_set_login_time(PurplePresence *presence, time_t login_time);
 298
 299 /**
 300  * purple_presence_get_statuses:
 301  * @presence: The presence.
 302  *
 303  * Returns all the statuses in a presence.
 304  *
 305  * Returns: (transfer none): The statuses.
 306  */
 307 GList *purple_presence_get_statuses(const PurplePresence *presence);
 308
 309 /**
 310  * purple_presence_get_status:
 311  * @presence:  The presence.
 312  * @status_id: The ID of the status.
 313  *
 314  * Returns the status with the specified ID from a presence.
 315  *
 316  * Returns: The status if found, or NULL.
 317  */
 318 PurpleStatus *purple_presence_get_status(const PurplePresence *presence,
 319                                                                          const char *status_id);
 320
 321 /**
 322  * purple_presence_get_active_status:
 323  * @presence: The presence.
 324  *
 325  * Returns the active exclusive status from a presence.
 326  *
 327  * Returns: The active exclusive status.
 328  */
 329 PurpleStatus *purple_presence_get_active_status(const PurplePresence *presence);
 330
 331 /**
 332  * purple_presence_is_available:
 333  * @presence: The presence.
 334  *
 335  * Returns whether or not a presence is available.
 336  *
 337  * Available presences are online and possibly invisible, but not away or idle.
 338  *
 339  * Returns: TRUE if the presence is available, or FALSE otherwise.
 340  */
 341 gboolean purple_presence_is_available(const PurplePresence *presence);
 342
 343 /**
 344  * purple_presence_is_online:
 345  * @presence: The presence.
 346  *
 347  * Returns whether or not a presence is online.
 348  *
 349  * Returns: TRUE if the presence is online, or FALSE otherwise.
 350  */
 351 gboolean purple_presence_is_online(const PurplePresence *presence);
 352
 353 /**
 354  * purple_presence_is_status_active:
 355  * @presence:  The presence.
 356  * @status_id: The ID of the status.
 357  *
 358  * Returns whether or not a status in a presence is active.
 359  *
 360  * A status is active if itself or any of its sub-statuses are active.
 361  *
 362  * Returns: TRUE if the status is active, or FALSE.
 363  */
 364 gboolean purple_presence_is_status_active(const PurplePresence *presence,
 365                                                                                 const char *status_id);
 366
 367 /**
 368  * purple_presence_is_status_primitive_active:
 369  * @presence:  The presence.
 370  * @primitive: The status primitive.
 371  *
 372  * Returns whether or not a status with the specified primitive type
 373  * in a presence is active.
 374  *
 375  * A status is active if itself or any of its sub-statuses are active.
 376  *
 377  * Returns: TRUE if the status is active, or FALSE.
 378  */
 379 gboolean purple_presence_is_status_primitive_active(
 380         const PurplePresence *presence, PurpleStatusPrimitive primitive);
 381
 382 /**
 383  * purple_presence_is_idle:
 384  * @presence: The presence.
 385  *
 386  * Returns whether or not a presence is idle.
 387  *
 388  * Returns: TRUE if the presence is idle, or FALSE otherwise.
 389  *         If the presence is offline (purple_presence_is_online()
 390  *         returns FALSE) then FALSE is returned.
 391  */
 392 gboolean purple_presence_is_idle(const PurplePresence *presence);
 393
 394 /**
 395  * purple_presence_get_idle_time:
 396  * @presence: The presence.
 397  *
 398  * Returns the presence's idle time.
 399  *
 400  * Returns: The presence's idle time.
 401  */
 402 time_t purple_presence_get_idle_time(const PurplePresence *presence);
 403
 404 /**
 405  * purple_presence_get_login_time:
 406  * @presence: The presence.
 407  *
 408  * Returns the presence's login time.
 409  *
 410  * Returns: The presence's login time.
 411  */
 412 time_t purple_presence_get_login_time(const PurplePresence *presence);
 413
 414 G_END_DECLS
 415
 416 #endif /* _PURPLE_PRESENCE_H_ */