libpurple/status.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_STATUS_H_
  24 #define _PURPLE_STATUS_H_
  25 /**
  26  * SECTION:status
  27  * @section_id: libpurple-status
  28  * @short_description: <filename>status.h</filename>
  29  * @title: Status Object API
  30  */
  31
  32 #define PURPLE_TYPE_STATUS             (purple_status_get_type())
  33 #define PURPLE_STATUS(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_STATUS, PurpleStatus))
  34 #define PURPLE_STATUS_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_STATUS, PurpleStatusClass))
  35 #define PURPLE_IS_STATUS(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_STATUS))
  36 #define PURPLE_IS_STATUS_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_STATUS))
  37 #define PURPLE_STATUS_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_STATUS, PurpleStatusClass))
  38
  39 typedef struct _PurpleStatus           PurpleStatus;
  40 typedef struct _PurpleStatusClass      PurpleStatusClass;
  41
  42 #define PURPLE_TYPE_STATUS_TYPE        (purple_status_type_get_type())
  43
  44 /**
  45  * PurpleStatusType:
  46  *
  47  * PurpleStatusType's are created by each protocol.  They outline the
  48  * available statuses of the protocol.  AIM, for example, supports
  49  * an available state with an optional available message, an away
  50  * state with a mandatory message, and an invisible state (which is
  51  * technically "independent" of the other two, but we'll get into
  52  * that later).  PurpleStatusTypes are very permanent.  They are
  53  * hardcoded in each protocol and will not change often.  And because
  54  * they are hardcoded, they do not need to be saved to any XML file.
  55  */
  56 typedef struct _PurpleStatusType       PurpleStatusType;
  57
  58 #define PURPLE_TYPE_STATUS_ATTRIBUTE   (purple_status_attribute_get_type())
  59
  60 typedef struct _PurpleStatusAttribute  PurpleStatusAttribute;
  61
  62 #define PURPLE_TYPE_MOOD               (purple_mood_get_type())
  63
  64 typedef struct _PurpleMood {
  65         const char *mood;
  66         const char *description;
  67         gpointer *padding;
  68 } PurpleMood;
  69
  70 /**
  71  * PurpleStatusPrimitive:
  72  *
  73  * @PURPLE_STATUS_UNSET: The status is not set
  74  * @PURPLE_STATUS_OFFLINE: The status is offline
  75  * @PURPLE_STATUS_AVAILABLE: The status is available
  76  * @PURPLE_STATUS_UNAVAILABLE: The status is unavailable
  77  * @PURPLE_STATUS_INVISIBLE: The stuatus is invisible
  78  * @PURPLE_STATUS_AWAY: The status is away
  79  * @PURPLE_STATUS_EXTENDED_AWAY: The status is extended away/do not disturb
  80  * @PURPLE_STATUS_MOBILE: The status is mobile
  81  * @PURPLE_STATUS_TUNE: The status includes a song title
  82  * @PURPLE_STATUS_MOOD: The status includes a mood
  83  * A primitive defining the basic structure of a status type.
  84  */
  85 /*
  86  * If you add a value to this enum, make sure you update
  87  * the status_primitive_map and primitive_scores arrays in status.c.
  88  */
  89 typedef enum
  90 {
  91         PURPLE_STATUS_UNSET = 0,
  92         PURPLE_STATUS_OFFLINE,
  93         PURPLE_STATUS_AVAILABLE,
  94         PURPLE_STATUS_UNAVAILABLE,
  95         PURPLE_STATUS_INVISIBLE,
  96         PURPLE_STATUS_AWAY,
  97         PURPLE_STATUS_EXTENDED_AWAY,
  98         PURPLE_STATUS_MOBILE,
  99         PURPLE_STATUS_TUNE,
 100         PURPLE_STATUS_MOOD,
 101
 102         /*< private >*/
 103         PURPLE_STATUS_NUM_PRIMITIVES, /*< skip >*/
 104 } PurpleStatusPrimitive;
 105
 106 #include "presence.h"
 107
 108 #define PURPLE_TUNE_ARTIST      "tune_artist"
 109 #define PURPLE_TUNE_TITLE       "tune_title"
 110 #define PURPLE_TUNE_ALBUM       "tune_album"
 111 #define PURPLE_TUNE_GENRE       "tune_genre"
 112 #define PURPLE_TUNE_COMMENT     "tune_comment"
 113 #define PURPLE_TUNE_TRACK       "tune_track"
 114 #define PURPLE_TUNE_TIME        "tune_time"
 115 #define PURPLE_TUNE_YEAR        "tune_year"
 116 #define PURPLE_TUNE_URL         "tune_url"
 117 #define PURPLE_TUNE_FULL        "tune_full"
 118
 119 #define PURPLE_MOOD_NAME        "mood"
 120 #define PURPLE_MOOD_COMMENT     "moodtext"
 121
 122 /**
 123  * PurpleStatus:
 124  *
 125  * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType.
 126  * If you're familiar with object-oriented programming languages
 127  * then this should be immediately clear.  Say, for example, that
 128  * one of your AIM buddies has set himself as "away."  You have a
 129  * PurpleBuddy node for this person in your buddy list.  Purple wants
 130  * to mark this buddy as "away," so it creates a new PurpleStatus.
 131  * The PurpleStatus has its PurpleStatusType set to the "away" state
 132  * for the oscar protocol.  The PurpleStatus also contains the buddy's
 133  * away message.  PurpleStatuses are sometimes saved, depending on
 134  * the context.  The current PurpleStatuses associated with each of
 135  * your accounts are saved so that the next time you start Purple,
 136  * your accounts will be set to their last known statuses.  There
 137  * is also a list of saved statuses that are written to the
 138  * status.xml file.  Also, each PurpleStatus has a "saveable" boolean.
 139  * If "saveable" is set to FALSE then the status is NEVER saved.
 140  * All PurpleStatuses should be inside a PurplePresence.
 141  *
 142  * A PurpleStatus is either "independent" or "exclusive."
 143  * Independent statuses can be active or inactive and they don't
 144  * affect anything else.  However, you can only have one exclusive
 145  * status per PurplePresence.  If you activate one exclusive status,
 146  * then the previous exclusive status is automatically deactivated.
 147  *
 148  * A PurplePresence is like a collection of PurpleStatuses (plus some
 149  * other random info).
 150  *
 151  * See <link linkend="libpurple-presence">Presence API</link>
 152  */
 153 struct _PurpleStatus
 154 {
 155         GObject gparent;
 156 };
 157
 158 /**
 159  * PurpleStatusClass:
 160  *
 161  * Base class for all #PurpleStatus's
 162  */
 163 struct _PurpleStatusClass {
 164         GObjectClass parent_class;
 165
 166         /*< private >*/
 167         void (*_purple_reserved1)(void);
 168         void (*_purple_reserved2)(void);
 169         void (*_purple_reserved3)(void);
 170         void (*_purple_reserved4)(void);
 171 };
 172
 173 G_BEGIN_DECLS
 174
 175 /**************************************************************************/
 176 /* PurpleStatusPrimitive API                                              */
 177 /**************************************************************************/
 178
 179 /**
 180  * purple_primitive_get_id_from_type:
 181  * @type: A primitive status type.
 182  *
 183  * Lookup the id of a primitive status type based on the type.  This
 184  * ID is a unique plain-text name of the status, without spaces.
 185  *
 186  * Returns: The unique ID for this type.
 187  */
 188 const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type);
 189
 190 /**
 191  * purple_primitive_get_name_from_type:
 192  * @type: A primitive status type.
 193  *
 194  * Lookup the name of a primitive status type based on the type.  This
 195  * name is the plain-English name of the status type.  It is usually one
 196  * or two words.
 197  *
 198  * Returns: The name of this type, suitable for users to see.
 199  */
 200 const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type);
 201
 202 /**
 203  * purple_primitive_get_type_from_id:
 204  * @id: The unique ID of a primitive status type.
 205  *
 206  * Lookup the value of a primitive status type based on the id.  The
 207  * ID is a unique plain-text name of the status, without spaces.
 208  *
 209  * Returns: The PurpleStatusPrimitive value.
 210  */
 211 PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id);
 212
 213 /**************************************************************************/
 214 /* PurpleStatusType API                                                   */
 215 /**************************************************************************/
 216
 217 /**
 218  * purple_status_type_get_type:
 219  *
 220  * Returns: The #GType for the #PurpleStatusType boxed structure.
 221  */
 222 GType purple_status_type_get_type(void);
 223
 224 /**
 225  * purple_status_type_new_full:
 226  * @primitive:     The primitive status type.
 227  * @id:            The ID of the status type, or %NULL to use the id of
 228  *                      the primitive status type.
 229  * @name:          The name presented to the user, or %NULL to use the
 230  *                      name of the primitive status type.
 231  * @saveable:      TRUE if the information set for this status by the
 232  *                      user can be saved for future sessions.
 233  * @user_settable: TRUE if this is a status the user can manually set.
 234  * @independent:   TRUE if this is an independent (non-exclusive)
 235  *                      status type.
 236  *
 237  * Creates a new status type.
 238  *
 239  * Returns: A new status type.
 240  */
 241 PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive,
 242                                                                                   const char *id, const char *name,
 243                                                                                   gboolean saveable,
 244                                                                                   gboolean user_settable,
 245                                                                                   gboolean independent);
 246
 247 /**
 248  * purple_status_type_new:
 249  * @primitive:     The primitive status type.
 250  * @id:            The ID of the status type, or %NULL to use the id of
 251  *                      the primitive status type.
 252  * @name:          The name presented to the user, or %NULL to use the
 253  *                      name of the primitive status type.
 254  * @user_settable: TRUE if this is a status the user can manually set.
 255  *
 256  * Creates a new status type with some default values (
 257  * saveable and not independent).
 258  *
 259  * Returns: A new status type.
 260  */
 261 PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive,
 262                                                                          const char *id, const char *name,
 263                                                                          gboolean user_settable);
 264
 265 /**
 266  * purple_status_type_new_with_attrs:
 267  * @primitive:     The primitive status type.
 268  * @id:            The ID of the status type, or %NULL to use the id of
 269  *                      the primitive status type.
 270  * @name:          The name presented to the user, or %NULL to use the
 271  *                      name of the primitive status type.
 272  * @saveable:      TRUE if the information set for this status by the
 273  *                      user can be saved for future sessions.
 274  * @user_settable: TRUE if this is a status the user can manually set.
 275  * @independent:   TRUE if this is an independent (non-exclusive)
 276  *                      status type.
 277  * @attr_id:       The ID of the first attribute.
 278  * @attr_name:     The name of the first attribute.
 279  * @attr_value:    The value type of the first attribute.
 280  * @...:           Additional attribute information.
 281  *
 282  * Creates a new status type with attributes.
 283  *
 284  * Returns: A new status type.
 285  */
 286 PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive,
 287                                                                                                 const char *id,
 288                                                                                                 const char *name,
 289                                                                                                 gboolean saveable,
 290                                                                                                 gboolean user_settable,
 291                                                                                                 gboolean independent,
 292                                                                                                 const char *attr_id,
 293                                                                                                 const char *attr_name,
 294                                                                                                 GValue *attr_value, ...) G_GNUC_NULL_TERMINATED;
 295
 296 /**
 297  * purple_status_type_destroy:
 298  * @status_type: The status type to destroy.
 299  *
 300  * Destroys a status type.
 301  */
 302 void purple_status_type_destroy(PurpleStatusType *status_type);
 303
 304 /**
 305  * purple_status_type_get_primitive:
 306  * @status_type: The status type.
 307  *
 308  * Returns the primitive type of a status type.
 309  *
 310  * Returns: The primitive type of the status type.
 311  */
 312 PurpleStatusPrimitive purple_status_type_get_primitive(
 313         const PurpleStatusType *status_type);
 314
 315 /**
 316  * purple_status_type_get_id:
 317  * @status_type: The status type.
 318  *
 319  * Returns the ID of a status type.
 320  *
 321  * Returns: The ID of the status type.
 322  */
 323 const char *purple_status_type_get_id(const PurpleStatusType *status_type);
 324
 325 /**
 326  * purple_status_type_get_name:
 327  * @status_type: The status type.
 328  *
 329  * Returns the name of a status type.
 330  *
 331  * Returns: The name of the status type.
 332  */
 333 const char *purple_status_type_get_name(const PurpleStatusType *status_type);
 334
 335 /**
 336  * purple_status_type_is_saveable:
 337  * @status_type: The status type.
 338  *
 339  * Returns whether or not the status type is saveable.
 340  *
 341  * Returns: TRUE if user-defined statuses based off this type are saveable.
 342  *         FALSE otherwise.
 343  */
 344 gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type);
 345
 346 /**
 347  * purple_status_type_is_user_settable:
 348  * @status_type: The status type.
 349  *
 350  * Returns whether or not the status type can be set or modified by the
 351  * user.
 352  *
 353  * Returns: TRUE if the status type can be set or modified by the user.
 354  *         FALSE if it's a protocol-set setting.
 355  */
 356 gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type);
 357
 358 /**
 359  * purple_status_type_is_independent:
 360  * @status_type: The status type.
 361  *
 362  * Returns whether or not the status type is independent.
 363  *
 364  * Independent status types are non-exclusive. If other status types on
 365  * the same hierarchy level are set, this one will not be affected.
 366  *
 367  * Returns: TRUE if the status type is independent, or FALSE otherwise.
 368  */
 369 gboolean purple_status_type_is_independent(const PurpleStatusType *status_type);
 370
 371 /**
 372  * purple_status_type_is_exclusive:
 373  * @status_type: The status type.
 374  *
 375  * Returns whether the status type is exclusive.
 376  *
 377  * Returns: TRUE if the status type is exclusive, FALSE otherwise.
 378  */
 379 gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type);
 380
 381 /**
 382  * purple_status_type_is_available:
 383  * @status_type: The status type.
 384  *
 385  * Returns whether or not a status type is available.
 386  *
 387  * Available status types are online and possibly invisible, but not away.
 388  *
 389  * Returns: TRUE if the status is available, or FALSE otherwise.
 390  */
 391 gboolean purple_status_type_is_available(const PurpleStatusType *status_type);
 392
 393 /**
 394  * purple_status_type_get_attr:
 395  * @status_type: The status type containing the attribute.
 396  * @id:          The ID of the desired attribute.
 397  *
 398  * Returns the attribute with the specified ID.
 399  *
 400  * Returns: The attribute, if found. NULL otherwise.
 401  */
 402 PurpleStatusAttribute *purple_status_type_get_attr(const PurpleStatusType *status_type,
 403                                                                                   const char *id);
 404
 405 /**
 406  * purple_status_type_get_attrs:
 407  * @status_type: The status type.
 408  *
 409  * Returns a list of all attributes in a status type.
 410  *
 411  * Returns: (transfer none): The list of attributes.
 412  */
 413 GList *purple_status_type_get_attrs(const PurpleStatusType *status_type);
 414
 415 /**
 416  * purple_status_type_find_with_id:
 417  * @status_types: A list of status types.  Often account->status_types.
 418  * @id: The unique ID of the status type you wish to find.
 419  *
 420  * Find the PurpleStatusType with the given id.
 421  *
 422  * Returns: The status type with the given ID, or NULL if one could
 423  *         not be found.
 424  */
 425 const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
 426                                                                                                         const char *id);
 427
 428 /**************************************************************************/
 429 /* PurpleStatusAttribute API                                              */
 430 /**************************************************************************/
 431
 432 /**
 433  * purple_status_attribute_get_type:
 434  *
 435  * Returns: The #GType for the #PurpleStatusAttribute boxed structure.
 436  */
 437 GType purple_status_attribute_get_type(void);
 438
 439 /**
 440  * purple_status_attribute_new:
 441  * @id:         The ID of the attribute.
 442  * @name:       The name presented to the user.
 443  * @value_type: The type of data contained in the attribute.
 444  *
 445  * Creates a new status attribute.
 446  *
 447  * Returns: A new status attribute.
 448  */
 449 PurpleStatusAttribute *purple_status_attribute_new(const char *id, const char *name,
 450                                                                          GValue *value_type);
 451
 452 /**
 453  * purple_status_attribute_destroy:
 454  * @attr: The status attribute to destroy.
 455  *
 456  * Destroys a status attribute.
 457  */
 458 void purple_status_attribute_destroy(PurpleStatusAttribute *attr);
 459
 460 /**
 461  * purple_status_attribute_get_id:
 462  * @attr: The status attribute.
 463  *
 464  * Returns the ID of a status attribute.
 465  *
 466  * Returns: The status attribute's ID.
 467  */
 468 const char *purple_status_attribute_get_id(const PurpleStatusAttribute *attr);
 469
 470 /**
 471  * purple_status_attribute_get_name:
 472  * @attr: The status attribute.
 473  *
 474  * Returns the name of a status attribute.
 475  *
 476  * Returns: The status attribute's name.
 477  */
 478 const char *purple_status_attribute_get_name(const PurpleStatusAttribute *attr);
 479
 480 /**
 481  * purple_status_attribute_get_value:
 482  * @attr: The status attribute.
 483  *
 484  * Returns the value of a status attribute.
 485  *
 486  * Returns: The status attribute's value.
 487  */
 488 GValue *purple_status_attribute_get_value(const PurpleStatusAttribute *attr);
 489
 490 /**************************************************************************/
 491 /* PurpleMood API                                                         */
 492 /**************************************************************************/
 493
 494 /**
 495  * purple_mood_get_type:
 496  *
 497  * Returns: The #GType for the #PurpleMood boxed structure.
 498  */
 499 GType purple_mood_get_type(void);
 500
 501 /**************************************************************************/
 502 /* PurpleStatus API                                                       */
 503 /**************************************************************************/
 504
 505 /**
 506  * purple_status_get_type:
 507  *
 508  * Returns: The #GType for the Status object.
 509  */
 510 GType purple_status_get_type(void);
 511
 512 /**
 513  * purple_status_new:
 514  * @status_type: The type of status.
 515  * @presence:    The parent presence.
 516  *
 517  * Creates a new status.
 518  *
 519  * Returns: The new status.
 520  */
 521 PurpleStatus *purple_status_new(PurpleStatusType *status_type,
 522                                                         PurplePresence *presence);
 523
 524 /**
 525  * purple_status_set_active:
 526  * @status: The status.
 527  * @active: The active state.
 528  *
 529  * Sets whether or not a status is active.
 530  *
 531  * This should only be called by the account, conversation, and buddy APIs.
 532  */
 533 void purple_status_set_active(PurpleStatus *status, gboolean active);
 534
 535 /**
 536  * purple_status_set_active_with_attrs:
 537  * @status: The status.
 538  * @active: The active state.
 539  * @args:   A list of attributes to set on the status.  This list is
 540  *               composed of key/value pairs, where each key is a valid
 541  *               attribute name for this PurpleStatusType.  The list should
 542  *               be NULL terminated.
 543  *
 544  * Sets whether or not a status is active.
 545  *
 546  * This should only be called by the account, conversation, and buddy APIs.
 547  */
 548 void purple_status_set_active_with_attrs(PurpleStatus *status, gboolean active,
 549                                                                            va_list args);
 550
 551 /**
 552  * purple_status_set_active_with_attrs_list:
 553  * @status: The status.
 554  * @active: The active state.
 555  * @attrs:  A list of attributes to set on the status.  This list is
 556  *               composed of key/value pairs, where each key is a valid
 557  *               attribute name for this PurpleStatusType.  The list is
 558  *               not modified or freed by this function.
 559  *
 560  * Sets whether or not a status is active.
 561  *
 562  * This should only be called by the account, conversation, and buddy APIs.
 563  */
 564 void purple_status_set_active_with_attrs_list(PurpleStatus *status, gboolean active,
 565                                                                                         GList *attrs);
 566
 567 /**
 568  * purple_status_get_status_type:
 569  * @status: The status.
 570  *
 571  * Returns the status's type.
 572  *
 573  * Returns: The status's type.
 574  */
 575 PurpleStatusType *purple_status_get_status_type(const PurpleStatus *status);
 576
 577 /**
 578  * purple_status_get_presence:
 579  * @status: The status.
 580  *
 581  * Returns the status's presence.
 582  *
 583  * Returns: The status's presence.
 584  */
 585 PurplePresence *purple_status_get_presence(const PurpleStatus *status);
 586
 587 /**
 588  * purple_status_get_id:
 589  * @status: The status.
 590  *
 591  * Returns the status's type ID.
 592  *
 593  * This is a convenience method for
 594  * purple_status_type_get_id(purple_status_get_status_type(status)).
 595  *
 596  * Returns: The status's ID.
 597  */
 598 const char *purple_status_get_id(const PurpleStatus *status);
 599
 600 /**
 601  * purple_status_get_name:
 602  * @status: The status.
 603  *
 604  * Returns the status's name.
 605  *
 606  * This is a convenience method for
 607  * purple_status_type_get_name(purple_status_get_status_type(status)).
 608  *
 609  * Returns: The status's name.
 610  */
 611 const char *purple_status_get_name(const PurpleStatus *status);
 612
 613 /**
 614  * purple_status_is_independent:
 615  * @status: The status.
 616  *
 617  * Returns whether or not a status is independent.
 618  *
 619  * This is a convenience method for
 620  * purple_status_type_is_independent(purple_status_get_status_type(status)).
 621  *
 622  * Returns: TRUE if the status is independent, or FALSE otherwise.
 623  */
 624 gboolean purple_status_is_independent(const PurpleStatus *status);
 625
 626 /**
 627  * purple_status_is_exclusive:
 628  * @status: The status.
 629  *
 630  * Returns whether or not a status is exclusive.
 631  *
 632  * This is a convenience method for
 633  * purple_status_type_is_exclusive(purple_status_get_status_type(status)).
 634  *
 635  * Returns: TRUE if the status is exclusive, FALSE otherwise.
 636  */
 637 gboolean purple_status_is_exclusive(const PurpleStatus *status);
 638
 639 /**
 640  * purple_status_is_available:
 641  * @status: The status.
 642  *
 643  * Returns whether or not a status is available.
 644  *
 645  * Available statuses are online and possibly invisible, but not away or idle.
 646  *
 647  * This is a convenience method for
 648  * purple_status_type_is_available(purple_status_get_status_type(status)).
 649  *
 650  * Returns: TRUE if the status is available, or FALSE otherwise.
 651  */
 652 gboolean purple_status_is_available(const PurpleStatus *status);
 653
 654 /**
 655  * purple_status_is_active:
 656  * @status: The status.
 657  *
 658  * Returns the active state of a status.
 659  *
 660  * Returns: The active state of the status.
 661  */
 662 gboolean purple_status_is_active(const PurpleStatus *status);
 663
 664 /**
 665  * purple_status_is_online:
 666  * @status: The status.
 667  *
 668  * Returns whether or not a status is considered 'online'
 669  *
 670  * Returns: TRUE if the status is considered online, FALSE otherwise
 671  */
 672 gboolean purple_status_is_online(const PurpleStatus *status);
 673
 674 /**
 675  * purple_status_get_attr_value:
 676  * @status: The status.
 677  * @id:     The attribute ID.
 678  *
 679  * Returns the value of an attribute in a status with the specified ID.
 680  *
 681  * Returns: The value of the attribute.
 682  */
 683 GValue *purple_status_get_attr_value(const PurpleStatus *status,
 684                                                                           const char *id);
 685
 686 /**
 687  * purple_status_get_attr_boolean:
 688  * @status: The status.
 689  * @id:     The attribute ID.
 690  *
 691  * Returns the boolean value of an attribute in a status with the specified ID.
 692  *
 693  * Returns: The boolean value of the attribute.
 694  */
 695 gboolean purple_status_get_attr_boolean(const PurpleStatus *status,
 696                                                                           const char *id);
 697
 698 /**
 699  * purple_status_get_attr_int:
 700  * @status: The status.
 701  * @id:     The attribute ID.
 702  *
 703  * Returns the integer value of an attribute in a status with the specified ID.
 704  *
 705  * Returns: The integer value of the attribute.
 706  */
 707 int purple_status_get_attr_int(const PurpleStatus *status, const char *id);
 708
 709 /**
 710  * purple_status_get_attr_string:
 711  * @status: The status.
 712  * @id:     The attribute ID.
 713  *
 714  * Returns the string value of an attribute in a status with the specified ID.
 715  *
 716  * Returns: The string value of the attribute.
 717  */
 718 const char *purple_status_get_attr_string(const PurpleStatus *status,
 719                                                                                 const char *id);
 720
 721 /**
 722  * purple_status_compare:
 723  * @status1: The first status.
 724  * @status2: The second status.
 725  *
 726  * Compares two statuses for availability.
 727  *
 728  * Returns: -1 if @status1 is more available than @status2.
 729  *           0 if @status1 is equal to @status2.
 730  *           1 if @status2 is more available than @status1.
 731  */
 732 gint purple_status_compare(const PurpleStatus *status1, const PurpleStatus *status2);
 733
 734 /**************************************************************************/
 735 /* Statuses subsystem                                                     */
 736 /**************************************************************************/
 737
 738 /**
 739  * purple_statuses_get_handle:
 740  *
 741  * Get the handle for the status subsystem.
 742  *
 743  * Returns: the handle to the status subsystem
 744  */
 745 void *purple_statuses_get_handle(void);
 746
 747 /**
 748  * purple_statuses_init:
 749  *
 750  * Initializes the status subsystem.
 751  */
 752 void purple_statuses_init(void);
 753
 754 /**
 755  * purple_statuses_uninit:
 756  *
 757  * Uninitializes the status subsystem.
 758  */
 759 void purple_statuses_uninit(void);
 760
 761 G_END_DECLS
 762
 763 #endif /* _PURPLE_STATUS_H_ */
 764