Mercurial > pidgin3 / file comparison

comparison: libgaim/status.h

libgaim/status.h

branch
gaim
changeset 20470
77693555855f
parent 12962
0f83f07e3ffe
parent 15124
68a8be380f54
child 20471
1966704b3e42
equal deleted inserted replaced
13071:b98e72d4089a 20470:77693555855f
1 /*
2 * gaim
3 *
4 * Gaim 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 */
22 #ifndef _GAIM_STATUS_H_
23 #define _GAIM_STATUS_H_
24
25 /**
26 * @file status.h Status API
27 * @ingroup core
28 *
29 * A brief explanation of the status API:
30 *
31 * GaimStatusType'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). GaimStatusTypes 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 GaimStatus can be thought of as an "instance" of a GaimStatusType.
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 * GaimBuddy node for this person in your buddy list. Gaim wants
45 * to mark this buddy as "away," so it creates a new GaimStatus.
46 * The GaimStatus has its GaimStatusType set to the "away" state
47 * for the oscar PRPL. The GaimStatus also contains the buddy's
48 * away message. GaimStatuses are sometimes saved, depending on
49 * the context. The current GaimStatuses associated with each of
50 * your accounts are saved so that the next time you start Gaim,
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 GaimStatus has a "savable" boolean.
54 * If "savable" is set to FALSE then the status is NEVER saved.
55 * All GaimStatuses should be inside a GaimPresence.
56 *
57 *
58 * A GaimStatus is either "indepedent" or "exclusive."
59 * Independent statuses can be active or inactive and it doesn't
60 * affect anything else. However, you can only have one exclusive
61 * status per GaimPresence. If you activate one exlusive status,
62 * then the previous exclusive status is automatically deactivated.
63 *
64 * A GaimPresence is like a collection of GaimStatuses (plus some
65 * other random info). For any buddy, or for any one of your accounts,
66 * or for any person you're chatting with, you may know various
67 * amounts of information. This information is all contained in
68 * one GaimPresence. If one of your buddies is away and idle,
69 * then the presence contains the GaimStatus for their awayness,
70 * and it contains their current idle time. GaimPresences are
71 * never saved to disk. The information they contain is only relevent
72 * for the current GaimSession.
73 */
74
75 typedef struct _GaimStatusType GaimStatusType;
76 typedef struct _GaimStatusAttr GaimStatusAttr;
77 typedef struct _GaimPresence GaimPresence;
78 typedef struct _GaimStatus GaimStatus;
79
80 /**
81 * A context for a presence.
82 *
83 * The context indicates what the presence applies to.
84 */
85 typedef enum
86 {
87 GAIM_PRESENCE_CONTEXT_UNSET = 0,
88 GAIM_PRESENCE_CONTEXT_ACCOUNT,
89 GAIM_PRESENCE_CONTEXT_CONV,
90 GAIM_PRESENCE_CONTEXT_BUDDY
91
92 } GaimPresenceContext;
93
94 /**
95 * A primitive defining the basic structure of a status type.
96 */
97 typedef enum
98 {
99 GAIM_STATUS_UNSET = 0,
100 GAIM_STATUS_OFFLINE,
101 GAIM_STATUS_AVAILABLE,
102 GAIM_STATUS_UNAVAILABLE,
103 GAIM_STATUS_INVISIBLE,
104 GAIM_STATUS_AWAY,
105 GAIM_STATUS_EXTENDED_AWAY,
106 GAIM_STATUS_MOBILE,
107 GAIM_STATUS_NUM_PRIMITIVES
108
109 } GaimStatusPrimitive;
110
111 #include "account.h"
112 #include "blist.h"
113 #include "conversation.h"
114 #include "value.h"
115
116 #ifdef __cplusplus
117 extern "C" {
118 #endif
119
120 /**************************************************************************/
121 /** @name GaimStatusPrimitive API */
122 /**************************************************************************/
123 /*@{*/
124
125 /**
126 * Lookup the id of a primitive status type based on the type. This
127 * ID is a unique plain-text name of the status, without spaces.
128 *
129 * @param type A primitive status type.
130 *
131 * @return The unique ID for this type.
132 */
133 const char *gaim_primitive_get_id_from_type(GaimStatusPrimitive type);
134
135 /**
136 * Lookup the name of a primitive status type based on the type. This
137 * name is the plain-English name of the status type. It is usually one
138 * or two words.
139 *
140 * @param type A primitive status type.
141 *
142 * @return The name of this type, suitable for users to see.
143 */
144 const char *gaim_primitive_get_name_from_type(GaimStatusPrimitive type);
145
146 /**
147 * Lookup the value of a primitive status type based on the id. The
148 * ID is a unique plain-text name of the status, without spaces.
149 *
150 * @param id The unique ID of a primitive status type.
151 *
152 * @return The GaimStatusPrimitive value.
153 */
154 GaimStatusPrimitive gaim_primitive_get_type_from_id(const char *id);
155
156 /*@}*/
157
158 /**************************************************************************/
159 /** @name GaimStatusType API */
160 /**************************************************************************/
161 /*@{*/
162
163 /**
164 * Creates a new status type.
165 *
166 * @param primitive The primitive status type.
167 * @param id The ID of the status type, or @c NULL to use the id of
168 * the primitive status type.
169 * @param name The name presented to the user, or @c NULL to use the
170 * name of the primitive status type.
171 * @param saveable TRUE if the information set for this status by the
172 * user can be saved for future sessions.
173 * @param user_settable TRUE if this is a status the user can manually set.
174 * @param independent TRUE if this is an independent (non-exclusive)
175 * status type.
176 *
177 * @return A new status type.
178 */
179 GaimStatusType *gaim_status_type_new_full(GaimStatusPrimitive primitive,
180 const char *id, const char *name,
181 gboolean saveable,
182 gboolean user_settable,
183 gboolean independent);
184
185 /**
186 * Creates a new status type with some default values (not
187 * savable and not independent).
188 *
189 * @param primitive The primitive status type.
190 * @param id The ID of the status type, or @c NULL to use the id of
191 * the primitive status type.
192 * @param name The name presented to the user, or @c NULL to use the
193 * name of the primitive status type.
194 * @param user_settable TRUE if this is a status the user can manually set.
195 *
196 * @return A new status type.
197 */
198 GaimStatusType *gaim_status_type_new(GaimStatusPrimitive primitive,
199 const char *id, const char *name,
200 gboolean user_settable);
201
202 /**
203 * Creates a new status type with attributes.
204 *
205 * @param primitive The primitive status type.
206 * @param id The ID of the status type, or @c NULL to use the id of
207 * the primitive status type.
208 * @param name The name presented to the user, or @c NULL to use the
209 * name of the primitive status type.
210 * @param saveable TRUE if the information set for this status by the
211 * user can be saved for future sessions.
212 * @param user_settable TRUE if this is a status the user can manually set.
213 * @param independent TRUE if this is an independent (non-exclusive)
214 * status type.
215 * @param attr_id The ID of the first attribute.
216 * @param attr_name The name of the first attribute.
217 * @param attr_value The value type of the first attribute attribute.
218 * @param ... Additional attribute information.
219 *
220 * @return A new status type.
221 */
222 GaimStatusType *gaim_status_type_new_with_attrs(GaimStatusPrimitive primitive,
223 const char *id,
224 const char *name,
225 gboolean saveable,
226 gboolean user_settable,
227 gboolean independent,
228 const char *attr_id,
229 const char *attr_name,
230 GaimValue *attr_value, ...);
231
232 /**
233 * Destroys a status type.
234 *
235 * @param status_type The status type to destroy.
236 */
237 void gaim_status_type_destroy(GaimStatusType *status_type);
238
239 /**
240 * Sets a status type's primary attribute.
241 *
242 * The value for the primary attribute is used as the description for
243 * the particular status type. An example is an away message. The message
244 * would be the primary attribute.
245 *
246 * @param status_type The status type.
247 * @param attr_id The ID of the primary attribute.
248 */
249 void gaim_status_type_set_primary_attr(GaimStatusType *status_type,
250 const char *attr_id);
251
252 /**
253 * Adds an attribute to a status type.
254 *
255 * @param status_type The status type to add the attribute to.
256 * @param id The ID of the attribute.
257 * @param name The name presented to the user.
258 * @param value The value type of this attribute.
259 */
260 void gaim_status_type_add_attr(GaimStatusType *status_type, const char *id,
261 const char *name, GaimValue *value);
262
263 /**
264 * Adds multiple attributes to a status type.
265 *
266 * @param status_type The status type to add the attribute to.
267 * @param id The ID of the first attribute.
268 * @param name The description of the first attribute.
269 * @param value The value type of the first attribute attribute.
270 * @param ... Additional attribute information.
271 */
272 void gaim_status_type_add_attrs(GaimStatusType *status_type, const char *id,
273 const char *name, GaimValue *value, ...);
274
275 /**
276 * Adds multiple attributes to a status type using a va_list.
277 *
278 * @param status_type The status type to add the attribute to.
279 * @param args The va_list of attributes.
280 */
281 void gaim_status_type_add_attrs_vargs(GaimStatusType *status_type,
282 va_list args);
283
284 /**
285 * Returns the primitive type of a status type.
286 *
287 * @param status_type The status type.
288 *
289 * @return The primitive type of the status type.
290 */
291 GaimStatusPrimitive gaim_status_type_get_primitive(
292 const GaimStatusType *status_type);
293
294 /**
295 * Returns the ID of a status type.
296 *
297 * @param status_type The status type.
298 *
299 * @return The ID of the status type.
300 */
301 const char *gaim_status_type_get_id(const GaimStatusType *status_type);
302
303 /**
304 * Returns the name of a status type.
305 *
306 * @param status_type The status type.
307 *
308 * @return The name of the status type.
309 */
310 const char *gaim_status_type_get_name(const GaimStatusType *status_type);
311
312 /**
313 * Returns whether or not the status type is saveable.
314 *
315 * @param status_type The status type.
316 *
317 * @return TRUE if user-defined statuses based off this type are saveable.
318 * FALSE otherwise.
319 */
320 gboolean gaim_status_type_is_saveable(const GaimStatusType *status_type);
321
322 /**
323 * Returns whether or not the status type can be set or modified by the
324 * user.
325 *
326 * @param status_type The status type.
327 *
328 * @return TRUE if the status type can be set or modified by the user.
329 * FALSE if it's a protocol-set setting.
330 */
331 gboolean gaim_status_type_is_user_settable(const GaimStatusType *status_type);
332
333 /**
334 * Returns whether or not the status type is independent.
335 *
336 * Independent status types are non-exclusive. If other status types on
337 * the same hierarchy level are set, this one will not be affected.
338 *
339 * @param status_type The status type.
340 *
341 * @return TRUE if the status type is independent, or FALSE otherwise.
342 */
343 gboolean gaim_status_type_is_independent(const GaimStatusType *status_type);
344
345 /**
346 * Returns whether the status type is exclusive.
347 *
348 * @param status_type The status type.
349 *
350 * @return TRUE if the status type is exclusive, FALSE otherwise.
351 */
352 gboolean gaim_status_type_is_exclusive(const GaimStatusType *status_type);
353
354 /**
355 * Returns whether or not a status type is available.
356 *
357 * Available status types are online and possibly invisible, but not away.
358 *
359 * @param status_type The status type.
360 *
361 * @return TRUE if the status is available, or FALSE otherwise.
362 */
363 gboolean gaim_status_type_is_available(const GaimStatusType *status_type);
364
365 /**
366 * Returns a status type's primary attribute ID.
367 *
368 * @param type The status type.
369 *
370 * @return The primary attribute's ID.
371 */
372 const char *gaim_status_type_get_primary_attr(const GaimStatusType *type);
373
374 /**
375 * Returns the attribute with the specified ID.
376 *
377 * @param status_type The status type containing the attribute.
378 * @param id The ID of the desired attribute.
379 *
380 * @return The attribute, if found. NULL otherwise.
381 */
382 GaimStatusAttr *gaim_status_type_get_attr(const GaimStatusType *status_type,
383 const char *id);
384
385 /**
386 * Returns a list of all attributes in a status type.
387 *
388 * @param status_type The status type.
389 *
390 * @return The list of attributes.
391 */
392 const GList *gaim_status_type_get_attrs(const GaimStatusType *status_type);
393
394 /**
395 * Find the GaimStatusType with the given id.
396 *
397 * @param status_types A list of status types. Often account->status_types.
398 * @param id The unique ID of the status type you wish to find.
399 *
400 * @return The status type with the given ID, or NULL if one could
401 * not be found.
402 */
403 const GaimStatusType *gaim_status_type_find_with_id(GList *status_types,
404 const char *id);
405
406 /*@}*/
407
408 /**************************************************************************/
409 /** @name GaimStatusAttr API */
410 /**************************************************************************/
411 /*@{*/
412
413 /**
414 * Creates a new status attribute.
415 *
416 * @param id The ID of the attribute.
417 * @param name The name presented to the user.
418 * @param value_type The type of data contained in the attribute.
419 *
420 * @return A new status attribute.
421 */
422 GaimStatusAttr *gaim_status_attr_new(const char *id, const char *name,
423 GaimValue *value_type);
424
425 /**
426 * Destroys a status attribute.
427 *
428 * @param attr The status attribute to destroy.
429 */
430 void gaim_status_attr_destroy(GaimStatusAttr *attr);
431
432 /**
433 * Returns the ID of a status attribute.
434 *
435 * @param attr The status attribute.
436 *
437 * @return The status attribute's ID.
438 */
439 const char *gaim_status_attr_get_id(const GaimStatusAttr *attr);
440
441 /**
442 * Returns the name of a status attribute.
443 *
444 * @param attr The status attribute.
445 *
446 * @return The status attribute's name.
447 */
448 const char *gaim_status_attr_get_name(const GaimStatusAttr *attr);
449
450 /**
451 * Returns the value of a status attribute.
452 *
453 * @param attr The status attribute.
454 *
455 * @return The status attribute's value.
456 */
457 GaimValue *gaim_status_attr_get_value(const GaimStatusAttr *attr);
458
459 /*@}*/
460
461 /**************************************************************************/
462 /** @name GaimStatus API */
463 /**************************************************************************/
464 /*@{*/
465
466 /**
467 * Creates a new status.
468 *
469 * @param status_type The type of status.
470 * @param presence The parent presence.
471 *
472 * @return The new status.
473 */
474 GaimStatus *gaim_status_new(GaimStatusType *status_type,
475 GaimPresence *presence);
476
477 /**
478 * Destroys a status.
479 *
480 * @param status The status to destroy.
481 */
482 void gaim_status_destroy(GaimStatus *status);
483
484 /**
485 * Sets whether or not a status is active.
486 *
487 * This should only be called by the account, conversation, and buddy APIs.
488 *
489 * @param status The status.
490 * @param active The active state.
491 */
492 void gaim_status_set_active(GaimStatus *status, gboolean active);
493
494 /**
495 * Sets whether or not a status is active.
496 *
497 * This should only be called by the account, conversation, and buddy APIs.
498 *
499 * @param status The status.
500 * @param active The active state.
501 * @param args A list of attributes to set on the status. This list is
502 * composed of key/value pairs, where each key is a valid
503 * attribute name for this GaimStatusType. The list should
504 * be NULL terminated.
505 */
506 void gaim_status_set_active_with_attrs(GaimStatus *status, gboolean active,
507 va_list args);
508
509 /**
510 * Sets whether or not a status is active.
511 *
512 * This should only be called by the account, conversation, and buddy APIs.
513 *
514 * @param status The status.
515 * @param active The active state.
516 * @param attrs A list of attributes to set on the status. This list is
517 * composed of key/value pairs, where each key is a valid
518 * attribute name for this GaimStatusType.
519 */
520 void gaim_status_set_active_with_attrs_list(GaimStatus *status, gboolean active,
521 const GList *attrs);
522
523 /**
524 * Sets the boolean value of an attribute in a status with the specified ID.
525 *
526 * @param status The status.
527 * @param id The attribute ID.
528 * @param value The boolean value.
529 */
530 void gaim_status_set_attr_boolean(GaimStatus *status, const char *id,
531 gboolean value);
532
533 /**
534 * Sets the integer value of an attribute in a status with the specified ID.
535 *
536 * @param status The status.
537 * @param id The attribute ID.
538 * @param value The integer value.
539 */
540 void gaim_status_set_attr_int(GaimStatus *status, const char *id,
541 int value);
542
543 /**
544 * Sets the string value of an attribute in a status with the specified ID.
545 *
546 * @param status The status.
547 * @param id The attribute ID.
548 * @param value The string value.
549 */
550 void gaim_status_set_attr_string(GaimStatus *status, const char *id,
551 const char *value);
552
553 /**
554 * Returns the status's type.
555 *
556 * @param status The status.
557 *
558 * @return The status's type.
559 */
560 GaimStatusType *gaim_status_get_type(const GaimStatus *status);
561
562 /**
563 * Returns the status's presence.
564 *
565 * @param status The status.
566 *
567 * @return The status's presence.
568 */
569 GaimPresence *gaim_status_get_presence(const GaimStatus *status);
570
571 /**
572 * Returns the status's type ID.
573 *
574 * This is a convenience method for
575 * gaim_status_type_get_id(gaim_status_get_type(status)).
576 *
577 * @param status The status.
578 *
579 * @return The status's ID.
580 */
581 const char *gaim_status_get_id(const GaimStatus *status);
582
583 /**
584 * Returns the status's name.
585 *
586 * This is a convenience method for
587 * gaim_status_type_get_name(gaim_status_get_type(status)).
588 *
589 * @param status The status.
590 *
591 * @return The status's name.
592 */
593 const char *gaim_status_get_name(const GaimStatus *status);
594
595 /**
596 * Returns whether or not a status is independent.
597 *
598 * This is a convenience method for
599 * gaim_status_type_is_independent(gaim_status_get_type(status)).
600 *
601 * @param status The status.
602 *
603 * @return TRUE if the status is independent, or FALSE otherwise.
604 */
605 gboolean gaim_status_is_independent(const GaimStatus *status);
606
607 /**
608 * Returns whether or not a status is exclusive.
609 *
610 * This is a convenience method for
611 * gaim_status_type_is_exclusive(gaim_status_get_type(status)).
612 *
613 * @param status The status.
614 *
615 * @return TRUE if the status is exclusive, FALSE otherwise.
616 */
617 gboolean gaim_status_is_exclusive(const GaimStatus *status);
618
619 /**
620 * Returns whether or not a status is available.
621 *
622 * Available statuses are online and possibly invisible, but not away or idle.
623 *
624 * This is a convenience method for
625 * gaim_status_type_is_available(gaim_status_get_type(status)).
626 *
627 * @param status The status.
628 *
629 * @return TRUE if the status is available, or FALSE otherwise.
630 */
631 gboolean gaim_status_is_available(const GaimStatus *status);
632
633 /**
634 * Returns the active state of a status.
635 *
636 * @param status The status.
637 *
638 * @return The active state of the status.
639 */
640 gboolean gaim_status_is_active(const GaimStatus *status);
641
642 /**
643 * Returns whether or not a status is considered 'online'
644 *
645 * @param status The status.
646 *
647 * @return TRUE if the status is considered online, FALSE otherwise
648 */
649 gboolean gaim_status_is_online(const GaimStatus *status);
650
651 /**
652 * Returns the value of an attribute in a status with the specified ID.
653 *
654 * @param status The status.
655 * @param id The attribute ID.
656 *
657 * @return The value of the attribute.
658 */
659 GaimValue *gaim_status_get_attr_value(const GaimStatus *status,
660 const char *id);
661
662 /**
663 * Returns the boolean value of an attribute in a status with the specified ID.
664 *
665 * @param status The status.
666 * @param id The attribute ID.
667 *
668 * @return The boolean value of the attribute.
669 */
670 gboolean gaim_status_get_attr_boolean(const GaimStatus *status,
671 const char *id);
672
673 /**
674 * Returns the integer value of an attribute in a status with the specified ID.
675 *
676 * @param status The status.
677 * @param id The attribute ID.
678 *
679 * @return The integer value of the attribute.
680 */
681 int gaim_status_get_attr_int(const GaimStatus *status, const char *id);
682
683 /**
684 * Returns the string value of an attribute in a status with the specified ID.
685 *
686 * @param status The status.
687 * @param id The attribute ID.
688 *
689 * @return The string value of the attribute.
690 */
691 const char *gaim_status_get_attr_string(const GaimStatus *status,
692 const char *id);
693
694 /**
695 * Compares two statuses for availability.
696 *
697 * @param status1 The first status.
698 * @param status2 The second status.
699 *
700 * @return -1 if @a status1 is more available than @a status2.
701 * 0 if @a status1 is equal to @a status2.
702 * 1 if @a status2 is more available than @a status1.
703 */
704 gint gaim_status_compare(const GaimStatus *status1, const GaimStatus *status2);
705
706 /*@}*/
707
708 /**************************************************************************/
709 /** @name GaimPresence API */
710 /**************************************************************************/
711 /*@{*/
712
713 /**
714 * Creates a new presence.
715 *
716 * @param context The presence context.
717 *
718 * @return A new presence.
719 */
720 GaimPresence *gaim_presence_new(GaimPresenceContext context);
721
722 /**
723 * Creates a presence for an account.
724 *
725 * @param account The account.
726 *
727 * @return The new presence.
728 */
729 GaimPresence *gaim_presence_new_for_account(GaimAccount *account);
730
731 /**
732 * Creates a presence for a conversation.
733 *
734 * @param conv The conversation.
735 *
736 * @return The new presence.
737 */
738 GaimPresence *gaim_presence_new_for_conv(GaimConversation *conv);
739
740 /**
741 * Creates a presence for a buddy.
742 *
743 * @param buddy The buddy.
744 *
745 * @return The new presence.
746 */
747 GaimPresence *gaim_presence_new_for_buddy(GaimBuddy *buddy);
748
749 /**
750 * Destroys a presence.
751 *
752 * All statuses added to this list will be destroyed along with
753 * the presence.
754 *
755 * If this presence belongs to a buddy, you must call
756 * gaim_presence_remove_buddy() first.
757 *
758 * @param presence The presence to destroy.
759 */
760 void gaim_presence_destroy(GaimPresence *presence);
761
762 /**
763 * Removes a buddy from a presence.
764 *
765 * This must be done before destroying a buddy in a presence.
766 *
767 * @param presence The presence.
768 * @param buddy The buddy.
769 */
770 void gaim_presence_remove_buddy(GaimPresence *presence, GaimBuddy *buddy);
771
772 /**
773 * Adds a status to a presence.
774 *
775 * @param presence The presence.
776 * @param status The status to add.
777 */
778 void gaim_presence_add_status(GaimPresence *presence, GaimStatus *status);
779
780 /**
781 * Adds a list of statuses to the presence.
782 *
783 * @param presence The presence.
784 * @param source_list The source list of statuses to add.
785 */
786 void gaim_presence_add_list(GaimPresence *presence, const GList *source_list);
787
788 /**
789 * Sets the active state of a status in a presence.
790 *
791 * Only independent statuses can be set unactive. Normal statuses can only
792 * be set active, so if you wish to disable a status, set another
793 * non-independent status to active, or use gaim_presence_switch_status().
794 *
795 * @param presence The presence.
796 * @param status_id The ID of the status.
797 * @param active The active state.
798 */
799 void gaim_presence_set_status_active(GaimPresence *presence,
800 const char *status_id, gboolean active);
801
802 /**
803 * Switches the active status in a presence.
804 *
805 * This is similar to gaim_presence_set_status_active(), except it won't
806 * activate independent statuses.
807 *
808 * @param presence The presence.
809 * @param status_id The status ID to switch to.
810 */
811 void gaim_presence_switch_status(GaimPresence *presence,
812 const char *status_id);
813
814 /**
815 * Sets the idle state and time on a presence.
816 *
817 * @param presence The presence.
818 * @param idle The idle state.
819 * @param idle_time The idle time, if @a idle is TRUE. This
820 * is the time at which the user became idle,
821 * in seconds since the epoch.
822 */
823 void gaim_presence_set_idle(GaimPresence *presence, gboolean idle,
824 time_t idle_time);
825
826 /**
827 * Sets the login time on a presence.
828 *
829 * @param presence The presence.
830 * @param login_time The login time.
831 */
832 void gaim_presence_set_login_time(GaimPresence *presence, time_t login_time);
833
834
835 /**
836 * Returns the presence's context.
837 *
838 * @param presence The presence.
839 *
840 * @return The presence's context.
841 */
842 GaimPresenceContext gaim_presence_get_context(const GaimPresence *presence);
843
844 /**
845 * Returns a presence's account.
846 *
847 * @param presence The presence.
848 *
849 * @return The presence's account.
850 */
851 GaimAccount *gaim_presence_get_account(const GaimPresence *presence);
852
853 /**
854 * Returns a presence's conversation.
855 *
856 * @param presence The presence.
857 *
858 * @return The presence's conversation.
859 */
860 GaimConversation *gaim_presence_get_conversation(const GaimPresence *presence);
861
862 /**
863 * Returns a presence's chat user.
864 *
865 * @param presence The presence.
866 *
867 * @return The chat's user.
868 */
869 const char *gaim_presence_get_chat_user(const GaimPresence *presence);
870
871 /**
872 * Returns a presence's list of buddies.
873 *
874 * @param presence The presence.
875 *
876 * @return The presence's list of buddies.
877 */
878 const GList *gaim_presence_get_buddies(const GaimPresence *presence);
879
880 /**
881 * Returns all the statuses in a presence.
882 *
883 * @param presence The presence.
884 *
885 * @return The statuses.
886 */
887 const GList *gaim_presence_get_statuses(const GaimPresence *presence);
888
889 /**
890 * Returns the status with the specified ID from a presence.
891 *
892 * @param presence The presence.
893 * @param status_id The ID of the status.
894 *
895 * @return The status if found, or NULL.
896 */
897 GaimStatus *gaim_presence_get_status(const GaimPresence *presence,
898 const char *status_id);
899
900 /**
901 * Returns the active exclusive status from a presence.
902 *
903 * @param presence The presence.
904 *
905 * @return The active exclusive status.
906 */
907 GaimStatus *gaim_presence_get_active_status(const GaimPresence *presence);
908
909 /**
910 * Returns whether or not a presence is available.
911 *
912 * Available presences are online and possibly invisible, but not away or idle.
913 *
914 * @param presence The presence.
915 *
916 * @return TRUE if the presence is available, or FALSE otherwise.
917 */
918 gboolean gaim_presence_is_available(const GaimPresence *presence);
919
920 /**
921 * Returns whether or not a presence is online.
922 *
923 * @param presence The presence.
924 *
925 * @return TRUE if the presence is online, or FALSE otherwise.
926 */
927 gboolean gaim_presence_is_online(const GaimPresence *presence);
928
929 /**
930 * Returns whether or not a status in a presence is active.
931 *
932 * A status is active if itself or any of its sub-statuses are active.
933 *
934 * @param presence The presence.
935 * @param status_id The ID of the status.
936 *
937 * @return TRUE if the status is active, or FALSE.
938 */
939 gboolean gaim_presence_is_status_active(const GaimPresence *presence,
940 const char *status_id);
941
942 /**
943 * Returns whether or not a status with the specified primitive type
944 * in a presence is active.
945 *
946 * A status is active if itself or any of its sub-statuses are active.
947 *
948 * @param presence The presence.
949 * @param primitive The status primitive.
950 *
951 * @return TRUE if the status is active, or FALSE.
952 */
953 gboolean gaim_presence_is_status_primitive_active(
954 const GaimPresence *presence, GaimStatusPrimitive primitive);
955
956 /**
957 * Returns whether or not a presence is idle.
958 *
959 * @param presence The presence.
960 *
961 * @return TRUE if the presence is idle, or FALSE otherwise.
962 * If the presence is offline (gaim_presence_is_online()
963 * returns FALSE) then FALSE is returned.
964 */
965 gboolean gaim_presence_is_idle(const GaimPresence *presence);
966
967 /**
968 * Returns the presence's idle time.
969 *
970 * @param presence The presence.
971 *
972 * @return The presence's idle time.
973 */
974 time_t gaim_presence_get_idle_time(const GaimPresence *presence);
975
976 /**
977 * Returns the presence's login time.
978 *
979 * @param presence The presence.
980 *
981 * @return The presence's login time.
982 */
983 time_t gaim_presence_get_login_time(const GaimPresence *presence);
984
985 /**
986 * Compares two presences for availability.
987 *
988 * @param presence1 The first presence.
989 * @param presence2 The second presence.
990 *
991 * @return -1 if @a presence1 is more available than @a presence2.
992 * 0 if @a presence1 is equal to @a presence2.
993 * 1 if @a presence1 is less available than @a presence2.
994 */
995 gint gaim_presence_compare(const GaimPresence *presence1,
996 const GaimPresence *presence2);
997
998 /*@}*/
999
1000 /**************************************************************************/
1001 /** @name Status subsystem */
1002 /**************************************************************************/
1003 /*@{*/
1004
1005 /**
1006 * Get the handle for the status subsystem.
1007 *
1008 * @return the handle to the status subsystem
1009 */
1010 void *gaim_status_get_handle(void);
1011
1012 /**
1013 * Initializes the status subsystem.
1014 */
1015 void gaim_status_init(void);
1016
1017 /**
1018 * Uninitializes the status subsystem.
1019 */
1020 void gaim_status_uninit(void);
1021
1022 /*@}*/
1023
1024 #ifdef __cplusplus
1025 }
1026 #endif
1027
1028 #endif /* _GAIM_STATUS_H_ */

Mercurial Repository: pidgin3

mercurial