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 #ifndef _PURPLE_STATUS_H_ 23 #define _PURPLE_STATUS_H_ 24 25 /** 26 * @file status.h Status API 27 * @ingroup core 28 * 29 * A brief explanation of the status API: 30 * 31 * PurpleStatusType's are created by each PRPL. They outline the 32 * available statuses of the protocol. AIM, for example, supports 33 * an available state with an optional available message, an away 34 * state with a mandatory message, and an invisible state (which is 35 * technically "independent" of the other two, but we'll get into 36 * that later). PurpleStatusTypes are very permanent. They are 37 * hardcoded in each PRPL and will not change often. And because 38 * they are hardcoded, they do not need to be saved to any XML file. 39 * 40 * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType. 41 * If you're familiar with object-oriented programming languages 42 * then this should be immediately clear. Say, for example, that 43 * one of your AIM buddies has set himself as "away." You have a 44 * PurpleBuddy node for this person in your buddy list. Purple wants 45 * to mark this buddy as "away," so it creates a new PurpleStatus. 46 * The PurpleStatus has its PurpleStatusType set to the "away" state 47 * for the oscar PRPL. The PurpleStatus also contains the buddy's 48 * away message. PurpleStatuses are sometimes saved, depending on 49 * the context. The current PurpleStatuses associated with each of 50 * your accounts are saved so that the next time you start Purple, 51 * your accounts will be set to their last known statuses. There 52 * is also a list of saved statuses that are written to the 53 * status.xml file. Also, each PurpleStatus has a "saveable" boolean. 54 * If "saveable" is set to FALSE then the status is NEVER saved. 55 * All PurpleStatuses should be inside a PurplePresence. 56 * 57 * 58 * A PurpleStatus is either "independent" or "exclusive." 59 * Independent statuses can be active or inactive and they don't 60 * affect anything else. However, you can only have one exclusive 61 * status per PurplePresence. If you activate one exclusive status, 62 * then the previous exclusive status is automatically deactivated. 63 * 64 * A PurplePresence is like a collection of PurpleStatuses (plus some 65 * other random info). For any buddy, or for any one of your accounts, 66 * or for any person with which you're chatting, you may know various 67 * amounts of information. This information is all contained in 68 * one PurplePresence. If one of your buddies is away and idle, 69 * then the presence contains the PurpleStatus for their awayness, 70 * and it contains their current idle time. PurplePresences are 71 * never saved to disk. The information they contain is only relevant 72 * for the current PurpleSession. 73 */ 74 75 /** 76 * PurpleStatusType's are created by each PRPL. They outline the 77 * available statuses of the protocol. AIM, for example, supports 78 * an available state with an optional available message, an away 79 * state with a mandatory message, and an invisible state (which is 80 * technically "independent" of the other two, but we'll get into 81 * that later). PurpleStatusTypes are very permanent. They are 82 * hardcoded in each PRPL and will not change often. And because 83 * they are hardcoded, they do not need to be saved to any XML file. 84 */ 85 typedef struct _PurpleStatusType PurpleStatusType; 86 typedef struct _PurpleStatusAttr PurpleStatusAttr; 87 typedef struct _PurplePresence PurplePresence; 88 typedef struct _PurpleStatus PurpleStatus; 89 90 typedef struct _PurpleMood { 91 const char *mood; 92 const char *description; 93 gpointer *padding; 94 } PurpleMood; 95 96 /** 97 * A context for a presence. 98 * 99 * The context indicates to what the presence applies. 100 */ 101 typedef enum 102 { 103 PURPLE_PRESENCE_CONTEXT_UNSET = 0, 104 PURPLE_PRESENCE_CONTEXT_ACCOUNT, 105 PURPLE_PRESENCE_CONTEXT_CONV, 106 PURPLE_PRESENCE_CONTEXT_BUDDY 107 108 } PurplePresenceContext; 109 110 /** 111 * A primitive defining the basic structure of a status type. 112 */ 113 /* 114 * If you add a value to this enum, make sure you update 115 * the status_primitive_map and primitive_scores arrays in status.c. 116 */ 117 typedef enum 118 { 119 PURPLE_STATUS_UNSET = 0, 120 PURPLE_STATUS_OFFLINE, 121 PURPLE_STATUS_AVAILABLE, 122 PURPLE_STATUS_UNAVAILABLE, 123 PURPLE_STATUS_INVISIBLE, 124 PURPLE_STATUS_AWAY, 125 PURPLE_STATUS_EXTENDED_AWAY, 126 PURPLE_STATUS_MOBILE, 127 PURPLE_STATUS_TUNE, 128 PURPLE_STATUS_MOOD, 129 PURPLE_STATUS_NUM_PRIMITIVES 130 } PurpleStatusPrimitive; 131 132 #include "account.h" 133 #include "blist.h" 134 #include "conversation.h" 135 #include "value.h" 136 137 #define PURPLE_TUNE_ARTIST "tune_artist" 138 #define PURPLE_TUNE_TITLE "tune_title" 139 #define PURPLE_TUNE_ALBUM "tune_album" 140 #define PURPLE_TUNE_GENRE "tune_genre" 141 #define PURPLE_TUNE_COMMENT "tune_comment" 142 #define PURPLE_TUNE_TRACK "tune_track" 143 #define PURPLE_TUNE_TIME "tune_time" 144 #define PURPLE_TUNE_YEAR "tune_year" 145 #define PURPLE_TUNE_URL "tune_url" 146 #define PURPLE_TUNE_FULL "tune_full" 147 148 #define PURPLE_MOOD_NAME "mood" 149 #define PURPLE_MOOD_COMMENT "moodtext" 150 151 #ifdef __cplusplus 152 extern "C" { 153 #endif 154 155 /**************************************************************************/ 156 /** @name PurpleStatusPrimitive API */ 157 /**************************************************************************/ 158 /*@{*/ 159 160 /** 161 * Lookup the id of a primitive status type based on the type. This 162 * ID is a unique plain-text name of the status, without spaces. 163 * 164 * @param type A primitive status type. 165 * 166 * @return The unique ID for this type. 167 */ 168 const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type); 169 170 /** 171 * Lookup the name of a primitive status type based on the type. This 172 * name is the plain-English name of the status type. It is usually one 173 * or two words. 174 * 175 * @param type A primitive status type. 176 * 177 * @return The name of this type, suitable for users to see. 178 */ 179 const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type); 180 181 /** 182 * Lookup the value of a primitive status type based on the id. The 183 * ID is a unique plain-text name of the status, without spaces. 184 * 185 * @param id The unique ID of a primitive status type. 186 * 187 * @return The PurpleStatusPrimitive value. 188 */ 189 PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id); 190 191 /*@}*/ 192 193 /**************************************************************************/ 194 /** @name PurpleStatusType API */ 195 /**************************************************************************/ 196 /*@{*/ 197 198 /** 199 * Creates a new status type. 200 * 201 * @param primitive The primitive status type. 202 * @param id The ID of the status type, or @c NULL to use the id of 203 * the primitive status type. 204 * @param name The name presented to the user, or @c NULL to use the 205 * name of the primitive status type. 206 * @param saveable TRUE if the information set for this status by the 207 * user can be saved for future sessions. 208 * @param user_settable TRUE if this is a status the user can manually set. 209 * @param independent TRUE if this is an independent (non-exclusive) 210 * status type. 211 * 212 * @return A new status type. 213 */ 214 PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive, 215 const char *id, const char *name, 216 gboolean saveable, 217 gboolean user_settable, 218 gboolean independent); 219 220 /** 221 * Creates a new status type with some default values ( 222 * saveable and not independent). 223 * 224 * @param primitive The primitive status type. 225 * @param id The ID of the status type, or @c NULL to use the id of 226 * the primitive status type. 227 * @param name The name presented to the user, or @c NULL to use the 228 * name of the primitive status type. 229 * @param user_settable TRUE if this is a status the user can manually set. 230 * 231 * @return A new status type. 232 */ 233 PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive, 234 const char *id, const char *name, 235 gboolean user_settable); 236 237 /** 238 * Creates a new status type with attributes. 239 * 240 * @param primitive The primitive status type. 241 * @param id The ID of the status type, or @c NULL to use the id of 242 * the primitive status type. 243 * @param name The name presented to the user, or @c NULL to use the 244 * name of the primitive status type. 245 * @param saveable TRUE if the information set for this status by the 246 * user can be saved for future sessions. 247 * @param user_settable TRUE if this is a status the user can manually set. 248 * @param independent TRUE if this is an independent (non-exclusive) 249 * status type. 250 * @param attr_id The ID of the first attribute. 251 * @param attr_name The name of the first attribute. 252 * @param attr_value The value type of the first attribute attribute. 253 * @param ... Additional attribute information. 254 * 255 * @return A new status type. 256 */ 257 PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive, 258 const char *id, 259 const char *name, 260 gboolean saveable, 261 gboolean user_settable, 262 gboolean independent, 263 const char *attr_id, 264 const char *attr_name, 265 PurpleValue *attr_value, ...) G_GNUC_NULL_TERMINATED; 266 267 /** 268 * Destroys a status type. 269 * 270 * @param status_type The status type to destroy. 271 */ 272 void purple_status_type_destroy(PurpleStatusType *status_type); 273 274 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 275 /** 276 * Sets a status type's primary attribute. 277 * 278 * The value for the primary attribute is used as the description for 279 * the particular status type. An example is an away message. The message 280 * would be the primary attribute. 281 * 282 * @param status_type The status type. 283 * @param attr_id The ID of the primary attribute. 284 * 285 * @deprecated This function isn't used and should be removed in 3.0.0. 286 */ 287 void purple_status_type_set_primary_attr(PurpleStatusType *status_type, 288 const char *attr_id); 289 #endif 290 291 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 292 /** 293 * Adds an attribute to a status type. 294 * 295 * @param status_type The status type to add the attribute to. 296 * @param id The ID of the attribute. 297 * @param name The name presented to the user. 298 * @param value The value type of this attribute. 299 * 300 * @deprecated This function isn't needed and should be removed in 3.0.0. 301 * Status type attributes should be set when the status type 302 * is created, in the call to purple_status_type_new_with_attrs. 303 */ 304 void purple_status_type_add_attr(PurpleStatusType *status_type, const char *id, 305 const char *name, PurpleValue *value); 306 #endif 307 308 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 309 /** 310 * Adds multiple attributes to a status type. 311 * 312 * @param status_type The status type to add the attribute to. 313 * @param id The ID of the first attribute. 314 * @param name The description of the first attribute. 315 * @param value The value type of the first attribute attribute. 316 * @param ... Additional attribute information. 317 * 318 * @deprecated This function isn't needed and should be removed in 3.0.0. 319 * Status type attributes should be set when the status type 320 * is created, in the call to purple_status_type_new_with_attrs. 321 */ 322 void purple_status_type_add_attrs(PurpleStatusType *status_type, const char *id, 323 const char *name, PurpleValue *value, ...) G_GNUC_NULL_TERMINATED; 324 #endif 325 326 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 327 /** 328 * Adds multiple attributes to a status type using a va_list. 329 * 330 * @param status_type The status type to add the attribute to. 331 * @param args The va_list of attributes. 332 * 333 * @deprecated This function isn't needed and should be removed in 3.0.0. 334 * Status type attributes should be set when the status type 335 * is created, in the call to purple_status_type_new_with_attrs. 336 */ 337 void purple_status_type_add_attrs_vargs(PurpleStatusType *status_type, 338 va_list args); 339 #endif 340 341 /** 342 * Returns the primitive type of a status type. 343 * 344 * @param status_type The status type. 345 * 346 * @return The primitive type of the status type. 347 */ 348 PurpleStatusPrimitive purple_status_type_get_primitive( 349 const PurpleStatusType *status_type); 350 351 /** 352 * Returns the ID of a status type. 353 * 354 * @param status_type The status type. 355 * 356 * @return The ID of the status type. 357 */ 358 const char *purple_status_type_get_id(const PurpleStatusType *status_type); 359 360 /** 361 * Returns the name of a status type. 362 * 363 * @param status_type The status type. 364 * 365 * @return The name of the status type. 366 */ 367 const char *purple_status_type_get_name(const PurpleStatusType *status_type); 368 369 /** 370 * Returns whether or not the status type is saveable. 371 * 372 * @param status_type The status type. 373 * 374 * @return TRUE if user-defined statuses based off this type are saveable. 375 * FALSE otherwise. 376 */ 377 gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type); 378 379 /** 380 * Returns whether or not the status type can be set or modified by the 381 * user. 382 * 383 * @param status_type The status type. 384 * 385 * @return TRUE if the status type can be set or modified by the user. 386 * FALSE if it's a protocol-set setting. 387 */ 388 gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type); 389 390 /** 391 * Returns whether or not the status type is independent. 392 * 393 * Independent status types are non-exclusive. If other status types on 394 * the same hierarchy level are set, this one will not be affected. 395 * 396 * @param status_type The status type. 397 * 398 * @return TRUE if the status type is independent, or FALSE otherwise. 399 */ 400 gboolean purple_status_type_is_independent(const PurpleStatusType *status_type); 401 402 /** 403 * Returns whether the status type is exclusive. 404 * 405 * @param status_type The status type. 406 * 407 * @return TRUE if the status type is exclusive, FALSE otherwise. 408 */ 409 gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type); 410 411 /** 412 * Returns whether or not a status type is available. 413 * 414 * Available status types are online and possibly invisible, but not away. 415 * 416 * @param status_type The status type. 417 * 418 * @return TRUE if the status is available, or FALSE otherwise. 419 */ 420 gboolean purple_status_type_is_available(const PurpleStatusType *status_type); 421 422 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 423 /** 424 * Returns a status type's primary attribute ID. 425 * 426 * @param type The status type. 427 * 428 * @return The primary attribute's ID. 429 * 430 * @deprecated This function isn't used and should be removed in 3.0.0. 431 */ 432 const char *purple_status_type_get_primary_attr(const PurpleStatusType *type); 433 #endif 434 435 /** 436 * Returns the attribute with the specified ID. 437 * 438 * @param status_type The status type containing the attribute. 439 * @param id The ID of the desired attribute. 440 * 441 * @return The attribute, if found. NULL otherwise. 442 */ 443 PurpleStatusAttr *purple_status_type_get_attr(const PurpleStatusType *status_type, 444 const char *id); 445 446 /** 447 * Returns a list of all attributes in a status type. 448 * 449 * @param status_type The status type. 450 * 451 * @constreturn The list of attributes. 452 */ 453 GList *purple_status_type_get_attrs(const PurpleStatusType *status_type); 454 455 /** 456 * Find the PurpleStatusType with the given id. 457 * 458 * @param status_types A list of status types. Often account->status_types. 459 * @param id The unique ID of the status type you wish to find. 460 * 461 * @return The status type with the given ID, or NULL if one could 462 * not be found. 463 */ 464 const PurpleStatusType *purple_status_type_find_with_id(GList *status_types, 465 const char *id); 466 467 /*@}*/ 468 469 /**************************************************************************/ 470 /** @name PurpleStatusAttr API */ 471 /**************************************************************************/ 472 /*@{*/ 473 474 /** 475 * Creates a new status attribute. 476 * 477 * @param id The ID of the attribute. 478 * @param name The name presented to the user. 479 * @param value_type The type of data contained in the attribute. 480 * 481 * @return A new status attribute. 482 */ 483 PurpleStatusAttr *purple_status_attr_new(const char *id, const char *name, 484 PurpleValue *value_type); 485 486 /** 487 * Destroys a status attribute. 488 * 489 * @param attr The status attribute to destroy. 490 */ 491 void purple_status_attr_destroy(PurpleStatusAttr *attr); 492 493 /** 494 * Returns the ID of a status attribute. 495 * 496 * @param attr The status attribute. 497 * 498 * @return The status attribute's ID. 499 */ 500 const char *purple_status_attr_get_id(const PurpleStatusAttr *attr); 501 502 /** 503 * Returns the name of a status attribute. 504 * 505 * @param attr The status attribute. 506 * 507 * @return The status attribute's name. 508 */ 509 const char *purple_status_attr_get_name(const PurpleStatusAttr *attr); 510 511 /** 512 * Returns the value of a status attribute. 513 * 514 * @param attr The status attribute. 515 * 516 * @return The status attribute's value. 517 */ 518 PurpleValue *purple_status_attr_get_value(const PurpleStatusAttr *attr); 519 520 /*@}*/ 521 522 /**************************************************************************/ 523 /** @name PurpleStatus API */ 524 /**************************************************************************/ 525 /*@{*/ 526 527 /** 528 * Creates a new status. 529 * 530 * @param status_type The type of status. 531 * @param presence The parent presence. 532 * 533 * @return The new status. 534 */ 535 PurpleStatus *purple_status_new(PurpleStatusType *status_type, 536 PurplePresence *presence); 537 538 /** 539 * Destroys a status. 540 * 541 * @param status The status to destroy. 542 */ 543 void purple_status_destroy(PurpleStatus *status); 544 545 /** 546 * Sets whether or not a status is active. 547 * 548 * This should only be called by the account, conversation, and buddy APIs. 549 * 550 * @param status The status. 551 * @param active The active state. 552 */ 553 void purple_status_set_active(PurpleStatus *status, gboolean active); 554 555 /** 556 * Sets whether or not a status is active. 557 * 558 * This should only be called by the account, conversation, and buddy APIs. 559 * 560 * @param status The status. 561 * @param active The active state. 562 * @param args A list of attributes to set on the status. This list is 563 * composed of key/value pairs, where each key is a valid 564 * attribute name for this PurpleStatusType. The list should 565 * be NULL terminated. 566 */ 567 void purple_status_set_active_with_attrs(PurpleStatus *status, gboolean active, 568 va_list args); 569 570 /** 571 * Sets whether or not a status is active. 572 * 573 * This should only be called by the account, conversation, and buddy APIs. 574 * 575 * @param status The status. 576 * @param active The active state. 577 * @param attrs A list of attributes to set on the status. This list is 578 * composed of key/value pairs, where each key is a valid 579 * attribute name for this PurpleStatusType. The list is 580 * not modified or freed by this function. 581 */ 582 void purple_status_set_active_with_attrs_list(PurpleStatus *status, gboolean active, 583 GList *attrs); 584 585 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 586 /** 587 * Sets the boolean value of an attribute in a status with the specified ID. 588 * 589 * @param status The status. 590 * @param id The attribute ID. 591 * @param value The boolean value. 592 * 593 * @deprecated This function is only used by status.c and should be made 594 * static in 3.0.0. 595 */ 596 void purple_status_set_attr_boolean(PurpleStatus *status, const char *id, 597 gboolean value); 598 #endif 599 600 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 601 /** 602 * Sets the integer value of an attribute in a status with the specified ID. 603 * 604 * @param status The status. 605 * @param id The attribute ID. 606 * @param value The integer value. 607 * 608 * @deprecated This function is only used by status.c and should be made 609 * static in 3.0.0. 610 */ 611 void purple_status_set_attr_int(PurpleStatus *status, const char *id, 612 int value); 613 #endif 614 615 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 616 /** 617 * Sets the string value of an attribute in a status with the specified ID. 618 * 619 * @param status The status. 620 * @param id The attribute ID. 621 * @param value The string value. 622 * 623 * @deprecated This function is only used by status.c and should be made 624 * static in 3.0.0. 625 */ 626 void purple_status_set_attr_string(PurpleStatus *status, const char *id, 627 const char *value); 628 #endif 629 630 /** 631 * Returns the status's type. 632 * 633 * @param status The status. 634 * 635 * @return The status's type. 636 */ 637 PurpleStatusType *purple_status_get_type(const PurpleStatus *status); 638 639 /** 640 * Returns the status's presence. 641 * 642 * @param status The status. 643 * 644 * @return The status's presence. 645 */ 646 PurplePresence *purple_status_get_presence(const PurpleStatus *status); 647 648 /** 649 * Returns the status's type ID. 650 * 651 * This is a convenience method for 652 * purple_status_type_get_id(purple_status_get_type(status)). 653 * 654 * @param status The status. 655 * 656 * @return The status's ID. 657 */ 658 const char *purple_status_get_id(const PurpleStatus *status); 659 660 /** 661 * Returns the status's name. 662 * 663 * This is a convenience method for 664 * purple_status_type_get_name(purple_status_get_type(status)). 665 * 666 * @param status The status. 667 * 668 * @return The status's name. 669 */ 670 const char *purple_status_get_name(const PurpleStatus *status); 671 672 /** 673 * Returns whether or not a status is independent. 674 * 675 * This is a convenience method for 676 * purple_status_type_is_independent(purple_status_get_type(status)). 677 * 678 * @param status The status. 679 * 680 * @return TRUE if the status is independent, or FALSE otherwise. 681 */ 682 gboolean purple_status_is_independent(const PurpleStatus *status); 683 684 /** 685 * Returns whether or not a status is exclusive. 686 * 687 * This is a convenience method for 688 * purple_status_type_is_exclusive(purple_status_get_type(status)). 689 * 690 * @param status The status. 691 * 692 * @return TRUE if the status is exclusive, FALSE otherwise. 693 */ 694 gboolean purple_status_is_exclusive(const PurpleStatus *status); 695 696 /** 697 * Returns whether or not a status is available. 698 * 699 * Available statuses are online and possibly invisible, but not away or idle. 700 * 701 * This is a convenience method for 702 * purple_status_type_is_available(purple_status_get_type(status)). 703 * 704 * @param status The status. 705 * 706 * @return TRUE if the status is available, or FALSE otherwise. 707 */ 708 gboolean purple_status_is_available(const PurpleStatus *status); 709 710 /** 711 * Returns the active state of a status. 712 * 713 * @param status The status. 714 * 715 * @return The active state of the status. 716 */ 717 gboolean purple_status_is_active(const PurpleStatus *status); 718 719 /** 720 * Returns whether or not a status is considered 'online' 721 * 722 * @param status The status. 723 * 724 * @return TRUE if the status is considered online, FALSE otherwise 725 */ 726 gboolean purple_status_is_online(const PurpleStatus *status); 727 728 /** 729 * Returns the value of an attribute in a status with the specified ID. 730 * 731 * @param status The status. 732 * @param id The attribute ID. 733 * 734 * @return The value of the attribute. 735 */ 736 PurpleValue *purple_status_get_attr_value(const PurpleStatus *status, 737 const char *id); 738 739 /** 740 * Returns the boolean value of an attribute in a status with the specified ID. 741 * 742 * @param status The status. 743 * @param id The attribute ID. 744 * 745 * @return The boolean value of the attribute. 746 */ 747 gboolean purple_status_get_attr_boolean(const PurpleStatus *status, 748 const char *id); 749 750 /** 751 * Returns the integer value of an attribute in a status with the specified ID. 752 * 753 * @param status The status. 754 * @param id The attribute ID. 755 * 756 * @return The integer value of the attribute. 757 */ 758 int purple_status_get_attr_int(const PurpleStatus *status, const char *id); 759 760 /** 761 * Returns the string value of an attribute in a status with the specified ID. 762 * 763 * @param status The status. 764 * @param id The attribute ID. 765 * 766 * @return The string value of the attribute. 767 */ 768 const char *purple_status_get_attr_string(const PurpleStatus *status, 769 const char *id); 770 771 /** 772 * Compares two statuses for availability. 773 * 774 * @param status1 The first status. 775 * @param status2 The second status. 776 * 777 * @return -1 if @a status1 is more available than @a status2. 778 * 0 if @a status1 is equal to @a status2. 779 * 1 if @a status2 is more available than @a status1. 780 */ 781 gint purple_status_compare(const PurpleStatus *status1, const PurpleStatus *status2); 782 783 /*@}*/ 784 785 /**************************************************************************/ 786 /** @name PurplePresence API */ 787 /**************************************************************************/ 788 /*@{*/ 789 790 /** 791 * Creates a new presence. 792 * 793 * @param context The presence context. 794 * 795 * @return A new presence. 796 */ 797 PurplePresence *purple_presence_new(PurplePresenceContext context); 798 799 /** 800 * Creates a presence for an account. 801 * 802 * @param account The account. 803 * 804 * @return The new presence. 805 */ 806 PurplePresence *purple_presence_new_for_account(PurpleAccount *account); 807 808 /** 809 * Creates a presence for a conversation. 810 * 811 * @param conv The conversation. 812 * 813 * @return The new presence. 814 */ 815 PurplePresence *purple_presence_new_for_conv(PurpleConversation *conv); 816 817 /** 818 * Creates a presence for a buddy. 819 * 820 * @param buddy The buddy. 821 * 822 * @return The new presence. 823 */ 824 PurplePresence *purple_presence_new_for_buddy(PurpleBuddy *buddy); 825 826 /** 827 * Destroys a presence. 828 * 829 * All statuses added to this list will be destroyed along with 830 * the presence. 831 * 832 * @param presence The presence to destroy. 833 */ 834 void purple_presence_destroy(PurplePresence *presence); 835 836 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 837 /** 838 * Adds a status to a presence. 839 * 840 * @param presence The presence. 841 * @param status The status to add. 842 * 843 * @deprecated This function is only used by purple_presence_add_list, 844 * and both should be removed in 3.0.0. 845 */ 846 void purple_presence_add_status(PurplePresence *presence, PurpleStatus *status); 847 #endif 848 849 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_) 850 /** 851 * Adds a list of statuses to the presence. 852 * 853 * @param presence The presence. 854 * @param source_list The source list of statuses to add, which is not 855 * modified or freed by this function. 856 * 857 * @deprecated This function isn't used and should be removed in 3.0.0. 858 */ 859 void purple_presence_add_list(PurplePresence *presence, GList *source_list); 860 #endif 861 862 /** 863 * Sets the active state of a status in a presence. 864 * 865 * Only independent statuses can be set unactive. Normal statuses can only 866 * be set active, so if you wish to disable a status, set another 867 * non-independent status to active, or use purple_presence_switch_status(). 868 * 869 * @param presence The presence. 870 * @param status_id The ID of the status. 871 * @param active The active state. 872 */ 873 void purple_presence_set_status_active(PurplePresence *presence, 874 const char *status_id, gboolean active); 875 876 /** 877 * Switches the active status in a presence. 878 * 879 * This is similar to purple_presence_set_status_active(), except it won't 880 * activate independent statuses. 881 * 882 * @param presence The presence. 883 * @param status_id The status ID to switch to. 884 */ 885 void purple_presence_switch_status(PurplePresence *presence, 886 const char *status_id); 887 888 /** 889 * Sets the idle state and time on a presence. 890 * 891 * @param presence The presence. 892 * @param idle The idle state. 893 * @param idle_time The idle time, if @a idle is TRUE. This 894 * is the time at which the user became idle, 895 * in seconds since the epoch. If this value is 896 * unknown then 0 should be used. 897 */ 898 void purple_presence_set_idle(PurplePresence *presence, gboolean idle, 899 time_t idle_time); 900 901 /** 902 * Sets the login time on a presence. 903 * 904 * @param presence The presence. 905 * @param login_time The login time. 906 */ 907 void purple_presence_set_login_time(PurplePresence *presence, time_t login_time); 908 909 910 /** 911 * Returns the presence's context. 912 * 913 * @param presence The presence. 914 * 915 * @return The presence's context. 916 */ 917 PurplePresenceContext purple_presence_get_context(const PurplePresence *presence); 918 919 /** 920 * Returns a presence's account. 921 * 922 * @param presence The presence. 923 * 924 * @return The presence's account. 925 */ 926 PurpleAccount *purple_presence_get_account(const PurplePresence *presence); 927 928 /** 929 * Returns a presence's conversation. 930 * 931 * @param presence The presence. 932 * 933 * @return The presence's conversation. 934 */ 935 PurpleConversation *purple_presence_get_conversation(const PurplePresence *presence); 936 937 /** 938 * Returns a presence's chat user. 939 * 940 * @param presence The presence. 941 * 942 * @return The chat's user. 943 */ 944 const char *purple_presence_get_chat_user(const PurplePresence *presence); 945 946 /** 947 * Returns the presence's buddy. 948 * 949 * @param presence The presence. 950 * 951 * @return The presence's buddy. 952 */ 953 PurpleBuddy *purple_presence_get_buddy(const PurplePresence *presence); 954 955 /** 956 * Returns all the statuses in a presence. 957 * 958 * @param presence The presence. 959 * 960 * @constreturn The statuses. 961 */ 962 GList *purple_presence_get_statuses(const PurplePresence *presence); 963 964 /** 965 * Returns the status with the specified ID from a presence. 966 * 967 * @param presence The presence. 968 * @param status_id The ID of the status. 969 * 970 * @return The status if found, or NULL. 971 */ 972 PurpleStatus *purple_presence_get_status(const PurplePresence *presence, 973 const char *status_id); 974 975 /** 976 * Returns the active exclusive status from a presence. 977 * 978 * @param presence The presence. 979 * 980 * @return The active exclusive status. 981 */ 982 PurpleStatus *purple_presence_get_active_status(const PurplePresence *presence); 983 984 /** 985 * Returns whether or not a presence is available. 986 * 987 * Available presences are online and possibly invisible, but not away or idle. 988 * 989 * @param presence The presence. 990 * 991 * @return TRUE if the presence is available, or FALSE otherwise. 992 */ 993 gboolean purple_presence_is_available(const PurplePresence *presence); 994 995 /** 996 * Returns whether or not a presence is online. 997 * 998 * @param presence The presence. 999 * 1000 * @return TRUE if the presence is online, or FALSE otherwise. 1001 */ 1002 gboolean purple_presence_is_online(const PurplePresence *presence); 1003 1004 /** 1005 * Returns whether or not a status in a presence is active. 1006 * 1007 * A status is active if itself or any of its sub-statuses are active. 1008 * 1009 * @param presence The presence. 1010 * @param status_id The ID of the status. 1011 * 1012 * @return TRUE if the status is active, or FALSE. 1013 */ 1014 gboolean purple_presence_is_status_active(const PurplePresence *presence, 1015 const char *status_id); 1016 1017 /** 1018 * Returns whether or not a status with the specified primitive type 1019 * in a presence is active. 1020 * 1021 * A status is active if itself or any of its sub-statuses are active. 1022 * 1023 * @param presence The presence. 1024 * @param primitive The status primitive. 1025 * 1026 * @return TRUE if the status is active, or FALSE. 1027 */ 1028 gboolean purple_presence_is_status_primitive_active( 1029 const PurplePresence *presence, PurpleStatusPrimitive primitive); 1030 1031 /** 1032 * Returns whether or not a presence is idle. 1033 * 1034 * @param presence The presence. 1035 * 1036 * @return TRUE if the presence is idle, or FALSE otherwise. 1037 * If the presence is offline (purple_presence_is_online() 1038 * returns FALSE) then FALSE is returned. 1039 */ 1040 gboolean purple_presence_is_idle(const PurplePresence *presence); 1041 1042 /** 1043 * Returns the presence's idle time. 1044 * 1045 * @param presence The presence. 1046 * 1047 * @return The presence's idle time. 1048 */ 1049 time_t purple_presence_get_idle_time(const PurplePresence *presence); 1050 1051 /** 1052 * Returns the presence's login time. 1053 * 1054 * @param presence The presence. 1055 * 1056 * @return The presence's login time. 1057 */ 1058 time_t purple_presence_get_login_time(const PurplePresence *presence); 1059 1060 /** 1061 * Compares two presences for availability. 1062 * 1063 * @param presence1 The first presence. 1064 * @param presence2 The second presence. 1065 * 1066 * @return -1 if @a presence1 is more available than @a presence2. 1067 * 0 if @a presence1 is equal to @a presence2. 1068 * 1 if @a presence1 is less available than @a presence2. 1069 */ 1070 gint purple_presence_compare(const PurplePresence *presence1, 1071 const PurplePresence *presence2); 1072 1073 /*@}*/ 1074 1075 /**************************************************************************/ 1076 /** @name Status subsystem */ 1077 /**************************************************************************/ 1078 /*@{*/ 1079 1080 /** 1081 * Get the handle for the status subsystem. 1082 * 1083 * @return the handle to the status subsystem 1084 */ 1085 void *purple_status_get_handle(void); 1086 1087 /** 1088 * Initializes the status subsystem. 1089 */ 1090 void purple_status_init(void); 1091 1092 /** 1093 * Uninitializes the status subsystem. 1094 */ 1095 void purple_status_uninit(void); 1096 1097 /*@}*/ 1098 1099 #ifdef __cplusplus 1100 } 1101 #endif 1102 1103 #endif /* _PURPLE_STATUS_H_ */ 1104