Mercurial > pidgin.yaz
comparison src/status.h @ 9944:e4a27c9aec4c
[gaim-migrate @ 10838]
with much rejoicing, and massive thanks to the efforts of Christian, and
all who have helped him, I present to you the incomplete status
rewrite!
committer: Tailor Script <tailor@pidgin.im>
author | Luke Schierer <lschiere@pidgin.im> |
---|---|
date | Fri, 03 Sep 2004 21:35:52 +0000 |
parents | fa6395637e2c |
children | dfc56946ef53 |
comparison
equal
deleted
inserted
replaced
9943:f8e395a054e2 | 9944:e4a27c9aec4c |
---|---|
1 /* | 1 /** |
2 * @file status.h Status API | |
3 * @ingroup core | |
4 * | |
2 * gaim | 5 * gaim |
3 * | 6 * |
4 * Gaim is the legal property of its developers, whose names are too numerous | 7 * 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 | 8 * to list here. Please refer to the COPYRIGHT file distributed with this |
6 * source distribution. | 9 * source distribution. |
7 * | 10 * |
8 * This program is free software; you can redistribute it and/or modify | 11 * 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 | 12 * 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 | 13 * the Free Software Foundation; either version 2 of the License, or |
11 * (at your option) any later version. | 14 * (at your option) any later version. |
12 * | 15 * |
17 * | 20 * |
18 * You should have received a copy of the GNU General Public License | 21 * You should have received a copy of the GNU General Public License |
19 * along with this program; if not, write to the Free Software | 22 * along with this program; if not, write to the Free Software |
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
21 */ | 24 */ |
22 | 25 #ifndef _GAIM_STATUS_H_ |
23 void gaim_status_sync(); | 26 #define _GAIM_STATUS_H_ |
24 void gaim_status_load(); | 27 |
28 typedef struct _GaimStatusType GaimStatusType; | |
29 typedef struct _GaimStatusAttr GaimStatusAttr; | |
30 typedef struct _GaimPresence GaimPresence; | |
31 typedef struct _GaimStatus GaimStatus; | |
32 | |
33 /** | |
34 * A context for a presence. | |
35 * | |
36 * The context indicates what the presence applies to. | |
37 */ | |
38 typedef enum | |
39 { | |
40 GAIM_PRESENCE_CONTEXT_UNSET = 0, | |
41 GAIM_PRESENCE_CONTEXT_ACCOUNT, | |
42 GAIM_PRESENCE_CONTEXT_CONV, | |
43 GAIM_PRESENCE_CONTEXT_BUDDY | |
44 | |
45 } GaimPresenceContext; | |
46 | |
47 /** | |
48 * A primitive defining the basic structure of a status type. | |
49 */ | |
50 typedef enum | |
51 { | |
52 GAIM_STATUS_UNSET = -1, | |
53 GAIM_STATUS_OFFLINE = 0, | |
54 GAIM_STATUS_ONLINE, | |
55 GAIM_STATUS_AVAILABLE, | |
56 GAIM_STATUS_UNAVAILABLE, | |
57 GAIM_STATUS_HIDDEN, | |
58 GAIM_STATUS_AWAY, | |
59 GAIM_STATUS_EXTENDED_AWAY | |
60 | |
61 } GaimStatusPrimitive; | |
62 | |
63 #include "account.h" | |
64 #include "blist.h" | |
65 #include "conversation.h" | |
66 #include "value.h" | |
67 | |
68 /**************************************************************************/ | |
69 /** @name GaimStatusType API */ | |
70 /**************************************************************************/ | |
71 /*@{*/ | |
72 | |
73 /** | |
74 * Creates a new status type. | |
75 * | |
76 * @param primitive The primitive status type. | |
77 * @param id The ID of the status type. | |
78 * @param name The name presented to the user. | |
79 * @param saveable TRUE if the information set for this status by the | |
80 * user can be saved for future sessions. | |
81 * @param user_settable TRUE if this is a status the user can manually set. | |
82 * @param independent TRUE if this is an independent (non-exclusive) | |
83 * status type. | |
84 * | |
85 * @return A new status type. | |
86 */ | |
87 GaimStatusType *gaim_status_type_new_full(GaimStatusPrimitive primitive, | |
88 const char *id, const char *name, | |
89 gboolean saveable, | |
90 gboolean user_settable, | |
91 gboolean independent); | |
92 | |
93 /** | |
94 * Creates a new status type with some default values. | |
95 * | |
96 * @param primitive The primitive status type. | |
97 * @param id The ID of the status type. | |
98 * @param name The name presented to the user. | |
99 * @param user_settable TRUE if this is a status the user can manually set. | |
100 * | |
101 * @return A new status type. | |
102 */ | |
103 GaimStatusType *gaim_status_type_new(GaimStatusPrimitive primitive, | |
104 const char *id, const char *name, | |
105 gboolean user_settable); | |
106 | |
107 /** | |
108 * Creates a new status type with attributes. | |
109 * | |
110 * @param primitive The primitive status type. | |
111 * @param id The ID of the status type. | |
112 * @param name The name presented to the user. | |
113 * @param saveable TRUE if the information set for this status by the | |
114 * user can be saved for future sessions. | |
115 * @param user_settable TRUE if this is a status the user can manually set. | |
116 * @param independent TRUE if this is an independent (non-exclusive) | |
117 * status type. | |
118 * @param attr_id The ID of the first attribute. | |
119 * @param attr_name The name of the first attribute. | |
120 * @param attr_value The value type of the first attribute attribute. | |
121 * @param ... Additional attribute information. | |
122 * | |
123 * @return A new status type. | |
124 */ | |
125 GaimStatusType *gaim_status_type_new_with_attrs(GaimStatusPrimitive primitive, | |
126 const char *id, | |
127 const char *name, | |
128 gboolean saveable, | |
129 gboolean user_settable, | |
130 gboolean independent, | |
131 const char *attr_id, | |
132 const char *attr_name, | |
133 GaimValue *attr_value, ...); | |
134 | |
135 /** | |
136 * Destroys a status type. | |
137 * | |
138 * @param status_type The status type to destroy. | |
139 */ | |
140 void gaim_status_type_destroy(GaimStatusType *status_type); | |
141 | |
142 /** | |
143 * Sets a status type's primary attribute. | |
144 * | |
145 * The value for the primary attribute is used as the description for | |
146 * the particular status type. An example is an away message. The message | |
147 * would be the primary attribute. | |
148 * | |
149 * @param status_type The status type. | |
150 * @param attr_id The ID of the primary attribute. | |
151 */ | |
152 void gaim_status_type_set_primary_attr(GaimStatusType *status_type, | |
153 const char *attr_id); | |
154 | |
155 /** | |
156 * Adds an attribute to a status type. | |
157 * | |
158 * @param status_type The status type to add the attribute to. | |
159 * @param id The ID of the attribute. | |
160 * @param name The name presented to the user. | |
161 * @param value The value type of this attribute. | |
162 */ | |
163 void gaim_status_type_add_attr(GaimStatusType *status_type, const char *id, | |
164 const char *name, GaimValue *value); | |
165 | |
166 /** | |
167 * Adds multiple attributes to a status type. | |
168 * | |
169 * @param status_type The status type to add the attribute to. | |
170 * @param id The ID of the first attribute. | |
171 * @param name The description of the first attribute. | |
172 * @param value The value type of the first attribute attribute. | |
173 * @param ... Additional attribute information. | |
174 */ | |
175 void gaim_status_type_add_attrs(GaimStatusType *status_type, const char *id, | |
176 const char *name, GaimValue *value, ...); | |
177 | |
178 /** | |
179 * Adds multiple attributes to a status type using a va_list. | |
180 * | |
181 * @param status_type The status type to add the attribute to. | |
182 * @param args The va_list of attributes. | |
183 */ | |
184 void gaim_status_type_add_attrs_vargs(GaimStatusType *status_type, | |
185 va_list args); | |
186 | |
187 /** | |
188 * Returns the primitive type of a status type. | |
189 * | |
190 * @param status_type The status type. | |
191 * | |
192 * @return The primitive type of the status type. | |
193 */ | |
194 GaimStatusPrimitive gaim_status_type_get_primitive( | |
195 const GaimStatusType *status_type); | |
196 | |
197 /** | |
198 * Returns the ID of a status type. | |
199 * | |
200 * @param status_type The status type. | |
201 * | |
202 * @return The ID of the status type. | |
203 */ | |
204 const char *gaim_status_type_get_id(const GaimStatusType *status_type); | |
205 | |
206 /** | |
207 * Returns the name of a status type. | |
208 * | |
209 * @param status_type The status type. | |
210 * | |
211 * @return The name of the status type. | |
212 */ | |
213 const char *gaim_status_type_get_name(const GaimStatusType *status_type); | |
214 | |
215 /** | |
216 * Returns whether or not the status type is saveable. | |
217 * | |
218 * @param status_type The status type. | |
219 * | |
220 * @return TRUE if user-defined statuses based off this type are saveable. | |
221 * FALSE otherwise. | |
222 */ | |
223 gboolean gaim_status_type_is_saveable(const GaimStatusType *status_type); | |
224 | |
225 /** | |
226 * Returns whether or not the status type can be set or modified by the | |
227 * user. | |
228 * | |
229 * @param status_type The status type. | |
230 * | |
231 * @return TRUE if the status type can be set or modified by the user. | |
232 * FALSE if it's a protocol-set setting. | |
233 */ | |
234 gboolean gaim_status_type_is_user_settable(const GaimStatusType *status_type); | |
235 | |
236 /** | |
237 * Returns whether or not the status type is independent. | |
238 * | |
239 * Independent status types are non-exclusive. If other status types on | |
240 * the same hierarchy level are set, this one will not be affected. | |
241 * | |
242 * @param status_type The status type. | |
243 * | |
244 * @return TRUE if the status type is independent, or FALSE otherwise. | |
245 */ | |
246 gboolean gaim_status_type_is_independent(const GaimStatusType *status_type); | |
247 | |
248 /** | |
249 * Returns whether or not a status type is available. | |
250 * | |
251 * Available status types are online and possibly hidden, but not away. | |
252 * | |
253 * @param status_type The status type. | |
254 * | |
255 * @return TRUE if the status is available, or FALSE otherwise. | |
256 */ | |
257 gboolean gaim_status_type_is_available(const GaimStatusType *status_type); | |
258 | |
259 /** | |
260 * Returns a status type's primary attribute ID. | |
261 * | |
262 * @param type The status type. | |
263 * | |
264 * @return The primary attribute's ID. | |
265 */ | |
266 const char *gaim_status_type_get_primary_attr(const GaimStatusType *type); | |
267 | |
268 /** | |
269 * Returns the attribute with the specified ID. | |
270 * | |
271 * @param status_type The status type containing the attribute. | |
272 * @param id The ID of the desired attribute. | |
273 * | |
274 * @return The attribute, if found. NULL otherwise. | |
275 */ | |
276 GaimStatusAttr *gaim_status_type_get_attr(const GaimStatusType *status_type, | |
277 const char *id); | |
278 | |
279 /** | |
280 * Returns a list of all attributes in a status type. | |
281 * | |
282 * @param status_type The status type. | |
283 * | |
284 * @return The list of attributes. | |
285 */ | |
286 const GList *gaim_status_type_get_attrs(const GaimStatusType *status_type); | |
287 | |
288 /*@}*/ | |
289 | |
290 /**************************************************************************/ | |
291 /** @name GaimStatusAttr API */ | |
292 /**************************************************************************/ | |
293 /*@{*/ | |
294 | |
295 /** | |
296 * Creates a new status attribute. | |
297 * | |
298 * @param id The ID of the attribute. | |
299 * @param name The name presented to the user. | |
300 * @param value_type The type of data contained in the attribute. | |
301 * | |
302 * @return A new status attribute. | |
303 */ | |
304 GaimStatusAttr *gaim_status_attr_new(const char *id, const char *name, | |
305 GaimValue *value_type); | |
306 | |
307 /** | |
308 * Destroys a status attribute. | |
309 * | |
310 * @param attr The status attribute to destroy. | |
311 */ | |
312 void gaim_status_attr_destroy(GaimStatusAttr *attr); | |
313 | |
314 /** | |
315 * Returns the ID of a status attribute. | |
316 * | |
317 * @param attr The status attribute. | |
318 * | |
319 * @return The status attribute's ID. | |
320 */ | |
321 const char *gaim_status_attr_get_id(const GaimStatusAttr *attr); | |
322 | |
323 /** | |
324 * Returns the name of a status attribute. | |
325 * | |
326 * @param attr The status attribute. | |
327 * | |
328 * @return The status attribute's name. | |
329 */ | |
330 const char *gaim_status_attr_get_name(const GaimStatusAttr *attr); | |
331 | |
332 /** | |
333 * Returns the value type of a status attribute. | |
334 * | |
335 * @param attr The status attribute. | |
336 * | |
337 * @return The status attribute's value type. | |
338 */ | |
339 GaimValue *gaim_status_attr_get_value_type(const GaimStatusAttr *attr); | |
340 | |
341 /*@}*/ | |
342 | |
343 /**************************************************************************/ | |
344 /** @name GaimStatus API */ | |
345 /**************************************************************************/ | |
346 /*@{*/ | |
347 | |
348 /** | |
349 * Creates a new status. | |
350 * | |
351 * @param status_type The type of status. | |
352 * @param presence The parent presence. | |
353 * | |
354 * @return The new status. | |
355 */ | |
356 GaimStatus *gaim_status_new(GaimStatusType *status_type, | |
357 GaimPresence *presence); | |
358 | |
359 /** | |
360 * Destroys a status. | |
361 * | |
362 * @param status The status to destroy. | |
363 */ | |
364 void gaim_status_destroy(GaimStatus *status); | |
365 | |
366 /** | |
367 * Sets whether or not a status is active. | |
368 * | |
369 * This should only be called by the account, conversation, and buddy APIs. | |
370 * | |
371 * @param status The status. | |
372 * @param active The active state. | |
373 */ | |
374 void gaim_status_set_active(GaimStatus *status, gboolean active); | |
375 | |
376 /** | |
377 * Sets the boolean value of an attribute in a status with the specified ID. | |
378 * | |
379 * @param status The status. | |
380 * @param id The attribute ID. | |
381 * @param value The boolean value. | |
382 */ | |
383 void gaim_status_set_attr_boolean(GaimStatus *status, const char *id, | |
384 gboolean value); | |
385 | |
386 /** | |
387 * Sets the integer value of an attribute in a status with the specified ID. | |
388 * | |
389 * @param status The status. | |
390 * @param id The attribute ID. | |
391 * @param value The integer value. | |
392 */ | |
393 void gaim_status_set_attr_int(GaimStatus *status, const char *id, | |
394 int value); | |
395 | |
396 /** | |
397 * Sets the string value of an attribute in a status with the specified ID. | |
398 * | |
399 * @param status The status. | |
400 * @param id The attribute ID. | |
401 * @param value The string value. | |
402 */ | |
403 void gaim_status_set_attr_string(GaimStatus *status, const char *id, | |
404 const char *value); | |
405 | |
406 /** | |
407 * Returns the status's type. | |
408 * | |
409 * @param status The status. | |
410 * | |
411 * @return The status's type. | |
412 */ | |
413 GaimStatusType *gaim_status_get_type(const GaimStatus *status); | |
414 | |
415 /** | |
416 * Returns the status's presence. | |
417 * | |
418 * @param status The status. | |
419 * | |
420 * @return The status's presence. | |
421 */ | |
422 GaimPresence *gaim_status_get_presence(const GaimStatus *status); | |
423 | |
424 /** | |
425 * Returns the status's type ID. | |
426 * | |
427 * This is a convenience method for | |
428 * gaim_status_type_get_id(gaim_status_get_type(status)). | |
429 * | |
430 * @param status The status. | |
431 * | |
432 * @return The status's ID. | |
433 */ | |
434 const char *gaim_status_get_id(const GaimStatus *status); | |
435 | |
436 /** | |
437 * Returns the status's name. | |
438 * | |
439 * This is a convenience method for | |
440 * gaim_status_type_get_name(gaim_status_get_type(status)). | |
441 * | |
442 * @param status The status. | |
443 * | |
444 * @return The status's name. | |
445 */ | |
446 const char *gaim_status_get_name(const GaimStatus *status); | |
447 | |
448 /** | |
449 * Returns whether or not a status is independent. | |
450 * | |
451 * This is a convenience method for | |
452 * gaim_status_type_is_independent(gaim_status_get_type(status)). | |
453 * | |
454 * @param status The status. | |
455 * | |
456 * @return TRUE if the status is independent, or FALSE otherwise. | |
457 */ | |
458 gboolean gaim_status_is_independent(const GaimStatus *status); | |
459 | |
460 /** | |
461 * Returns whether or not a status is available. | |
462 * | |
463 * Available statuses are online and possibly hidden, but not away or idle. | |
464 * | |
465 * This is a convenience method for | |
466 * gaim_status_type_is_available(gaim_status_get_type(status)). | |
467 * | |
468 * @param status The status. | |
469 * | |
470 * @return TRUE if the status is available, or FALSE otherwise. | |
471 */ | |
472 gboolean gaim_status_is_available(const GaimStatus *status); | |
473 | |
474 /** | |
475 * Returns the active state of a status. | |
476 * | |
477 * @param status The status. | |
478 * | |
479 * @return The active state of the status. | |
480 */ | |
481 gboolean gaim_status_is_active(const GaimStatus *status); | |
482 | |
483 /** | |
484 * Returns the value of an attribute in a status with the specified ID. | |
485 * | |
486 * @param status The status. | |
487 * @param id The attribute ID. | |
488 * | |
489 * @return The value of the attribute. | |
490 */ | |
491 GaimValue *gaim_status_get_attr_value(const GaimStatus *status, | |
492 const char *id); | |
493 | |
494 /** | |
495 * Returns the boolean value of an attribute in a status with the specified ID. | |
496 * | |
497 * @param status The status. | |
498 * @param id The attribute ID. | |
499 * | |
500 * @return The boolean value of the attribute. | |
501 */ | |
502 gboolean gaim_status_get_attr_boolean(const GaimStatus *status, | |
503 const char *id); | |
504 | |
505 /** | |
506 * Returns the integer value of an attribute in a status with the specified ID. | |
507 * | |
508 * @param status The status. | |
509 * @param id The attribute ID. | |
510 * | |
511 * @return The integer value of the attribute. | |
512 */ | |
513 int gaim_status_get_attr_int(const GaimStatus *status, const char *id); | |
514 | |
515 /** | |
516 * Returns the string value of an attribute in a status with the specified ID. | |
517 * | |
518 * @param status The status. | |
519 * @param id The attribute ID. | |
520 * | |
521 * @return The string value of the attribute. | |
522 */ | |
523 const char *gaim_status_get_attr_string(const GaimStatus *status, | |
524 const char *id); | |
525 | |
526 /** | |
527 * Compares two statuses for availability. | |
528 * | |
529 * @param status1 The first status. | |
530 * @param status2 The second status. | |
531 * | |
532 * @return -1 if @a status1 is more available than @a status2. | |
533 * 0 if @a status1 is equal to @a status2. | |
534 * 1 if @a status2 is more available than @a status1. | |
535 */ | |
536 gint gaim_status_compare(const GaimStatus *status1, const GaimStatus *status2); | |
537 | |
538 /*@}*/ | |
539 | |
540 /**************************************************************************/ | |
541 /** @name GaimPresence API */ | |
542 /**************************************************************************/ | |
543 /*@{*/ | |
544 | |
545 /** | |
546 * Creates a new presence. | |
547 * | |
548 * @param context The presence context. | |
549 * | |
550 * @return A new presence. | |
551 */ | |
552 GaimPresence *gaim_presence_new(GaimPresenceContext context); | |
553 | |
554 /** | |
555 * Creates a presence for an account. | |
556 * | |
557 * @param account The account. | |
558 * | |
559 * @return The new presence. | |
560 */ | |
561 GaimPresence *gaim_presence_new_for_account(GaimAccount *account); | |
562 | |
563 /** | |
564 * Creates a presence for a conversation. | |
565 * | |
566 * @param conv The conversation. | |
567 * | |
568 * @return The new presence. | |
569 */ | |
570 GaimPresence *gaim_presence_new_for_conv(GaimConversation *conv); | |
571 | |
572 /** | |
573 * Creates a presence for a buddy. | |
574 * | |
575 * @param buddy The buddy. | |
576 * | |
577 * @return The new presence. | |
578 */ | |
579 GaimPresence *gaim_presence_new_for_buddy(GaimBuddy *buddy); | |
580 | |
581 /** | |
582 * Destroys a presence. | |
583 * | |
584 * All statuses added to this list will be destroyed along with | |
585 * the presence. | |
586 * | |
587 * If this presence belongs to a buddy, you must call | |
588 * gaim_presence_remove_buddy() first. | |
589 * | |
590 * @param presence The presence to destroy. | |
591 */ | |
592 void gaim_presence_destroy(GaimPresence *presence); | |
593 | |
594 /** | |
595 * Removes a buddy from a presence. | |
596 * | |
597 * This must be done before destroying a buddy in a presence. | |
598 * | |
599 * @param presence The presence. | |
600 * @param buddy The buddy. | |
601 */ | |
602 void gaim_presence_remove_buddy(GaimPresence *presence, GaimBuddy *buddy); | |
603 | |
604 /** | |
605 * Adds a status to a presence. | |
606 * | |
607 * @param presence The presence. | |
608 * @param status The status to add. | |
609 */ | |
610 void gaim_presence_add_status(GaimPresence *presence, GaimStatus *status); | |
611 | |
612 /** | |
613 * Adds a list of statuses to the presence. | |
614 * | |
615 * @param presence The presence. | |
616 * @param source_list The source list of statuses to add. | |
617 */ | |
618 void gaim_presence_add_list(GaimPresence *presence, const GList *source_list); | |
619 | |
620 /** | |
621 * Sets the active state of a status in a presence. | |
622 * | |
623 * Only independent statuses can be set unactive. Normal statuses can only | |
624 * be set active, so if you wish to disable a status, set another | |
625 * non-independent status to active, or use gaim_presence_switch_status(). | |
626 * | |
627 * @param presence The presence. | |
628 * @param status_id The ID of the status. | |
629 * @param active The active state. | |
630 */ | |
631 void gaim_presence_set_status_active(GaimPresence *presence, | |
632 const char *status_id, gboolean active); | |
633 | |
634 /** | |
635 * Switches the active status in a presence. | |
636 * | |
637 * This is similar to gaim_presence_set_status_active(), except it won't | |
638 * activate independent statuses. | |
639 * | |
640 * @param presence The presence. | |
641 * @param status_id The status ID to switch to. | |
642 */ | |
643 void gaim_presence_switch_status(GaimPresence *presence, | |
644 const char *status_id); | |
645 | |
646 /** | |
647 * Sets the idle state and time on a presence. | |
648 * | |
649 * @param presence The presence. | |
650 * @param idle The idle state. | |
651 * @param idle_time The idle time, if @a idle is TRUE. | |
652 */ | |
653 void gaim_presence_set_idle(GaimPresence *presence, gboolean idle, | |
654 time_t idle_time); | |
655 | |
656 /** | |
657 * Sets the warning level on a presence. | |
658 * | |
659 * @param presence The presence. | |
660 * @param level The warning level. | |
661 */ | |
662 void gaim_presence_set_warning_level(GaimPresence *presence, | |
663 unsigned int level); | |
664 | |
665 /** | |
666 * Returns the presence's context. | |
667 * | |
668 * @param presence The presence. | |
669 * | |
670 * @return The presence's context. | |
671 */ | |
672 GaimPresenceContext gaim_presence_get_context(const GaimPresence *presence); | |
673 | |
674 /** | |
675 * Returns a presence's account. | |
676 * | |
677 * @param presence The presence. | |
678 * | |
679 * @return The presence's account. | |
680 */ | |
681 GaimAccount *gaim_presence_get_account(const GaimPresence *presence); | |
682 | |
683 /** | |
684 * Returns a presence's conversation. | |
685 * | |
686 * @param presence The presence. | |
687 * | |
688 * @return The presence's conversation. | |
689 */ | |
690 GaimConversation *gaim_presence_get_conversation(const GaimPresence *presence); | |
691 | |
692 /** | |
693 * Returns a presence's chat user. | |
694 * | |
695 * @param presence The presence. | |
696 * | |
697 * @return The chat's user. | |
698 */ | |
699 const char *gaim_presence_get_chat_user(const GaimPresence *presence); | |
700 | |
701 /** | |
702 * Returns a presence's list of buddies. | |
703 * | |
704 * @param presence The presence. | |
705 * | |
706 * @return The presence's list of buddies. | |
707 */ | |
708 const GList *gaim_presence_get_buddies(const GaimPresence *presence); | |
709 | |
710 /** | |
711 * Returns all the statuses in a presence. | |
712 * | |
713 * @param presence The presence. | |
714 * | |
715 * @return The statuses. | |
716 */ | |
717 const GList *gaim_presence_get_statuses(const GaimPresence *presence); | |
718 | |
719 /** | |
720 * Returns the status with the specified ID from a presence. | |
721 * | |
722 * @param presence The presence. | |
723 * @param status_id The ID of the status. | |
724 * | |
725 * @return The status if found, or NULL. | |
726 */ | |
727 GaimStatus *gaim_presence_get_status(const GaimPresence *presence, | |
728 const char *status_id); | |
729 | |
730 /** | |
731 * Returns the active exclusive status from a presence. | |
732 * | |
733 * @param presence The presence. | |
734 * | |
735 * @return The active exclusive status. | |
736 */ | |
737 GaimStatus *gaim_presence_get_active_status(const GaimPresence *presence); | |
738 | |
739 /** | |
740 * Returns whether or not a presence is available. | |
741 * | |
742 * Available presences are online and possibly hidden, but not away or idle. | |
743 * | |
744 * @param presence The presence. | |
745 * | |
746 * @return TRUE if the presence is available, or FALSE otherwise. | |
747 */ | |
748 gboolean gaim_presence_is_available(const GaimPresence *presence); | |
749 | |
750 /** | |
751 * Returns whether or not a presence is online. | |
752 * | |
753 * @param presence The presence. | |
754 * | |
755 * @return TRUE if the presence is online, or FALSE otherwise. | |
756 */ | |
757 gboolean gaim_presence_is_online(const GaimPresence *presence); | |
758 | |
759 /** | |
760 * Returns whether or not a status in a presence is active. | |
761 * | |
762 * A status is active if itself or any of its sub-statuses are active. | |
763 * | |
764 * @param presence The presence. | |
765 * @param status_id The ID of the status. | |
766 * | |
767 * @return TRUE if the status is active, or FALSE. | |
768 */ | |
769 gboolean gaim_presence_is_status_active(const GaimPresence *presence, | |
770 const char *status_id); | |
771 | |
772 /** | |
773 * Returns whether or not a status with the specified primitive type | |
774 * in a presence is active. | |
775 * | |
776 * A status is active if itself or any of its sub-statuses are active. | |
777 * | |
778 * @param presence The presence. | |
779 * @param primitive The status primitive. | |
780 * | |
781 * @return TRUE if the status is active, or FALSE. | |
782 */ | |
783 gboolean gaim_presence_is_status_primitive_active( | |
784 const GaimPresence *presence, GaimStatusPrimitive primitive); | |
785 | |
786 /** | |
787 * Returns whether or not a presence is idle. | |
788 * | |
789 * @param presence The presence. | |
790 * | |
791 * @return TRUE if the presence is idle, or FALSE otherwise. | |
792 */ | |
793 gboolean gaim_presence_is_idle(const GaimPresence *presence); | |
794 | |
795 /** | |
796 * Returns the presence's idle time. | |
797 * | |
798 * @param presence The presence. | |
799 * | |
800 * @return The presence's idle time. | |
801 */ | |
802 time_t gaim_presence_get_idle_time(const GaimPresence *presence); | |
803 | |
804 /** | |
805 * Returns the presence's warning level. | |
806 * | |
807 * @param presence The presence. | |
808 * | |
809 * @return The presence's warning level. | |
810 */ | |
811 unsigned int gaim_presence_get_warning_level(const GaimPresence *presence); | |
812 | |
813 /** | |
814 * Compares two presences for availability. | |
815 * | |
816 * @param presence1 The first presence. | |
817 * @param presence2 The second presence. | |
818 * | |
819 * @return -1 if @a presence1 is less available than @a presence2. | |
820 * 0 if @a presence1 is equal to @a presence2. | |
821 * 1 if @a presence2 is more available than @a presence1. | |
822 */ | |
823 gint gaim_presence_compare(const GaimPresence *presence1, | |
824 const GaimPresence *presence2); | |
825 | |
826 /*@}*/ | |
827 | |
828 | |
829 /**************************************************************************/ | |
830 /** @name Status subsystem */ | |
831 /**************************************************************************/ | |
832 /*@{*/ | |
833 | |
834 /** | |
835 * Returns all stored statuses. | |
836 * | |
837 * @return A list of stored statuses. | |
838 */ | |
839 const GList *gaim_statuses_get_stored(void); | |
840 | |
841 /** | |
842 * Finds a stored status with the specified status type and primary ID. | |
843 * | |
844 * @param status_type The status type of the status. | |
845 * @param id The primary attribute ID. | |
846 * | |
847 * @return The stored status if found, or NULL. | |
848 */ | |
849 GaimStatus *gaim_statuses_find_stored(const GaimStatusType *status_type, | |
850 const char *id); | |
851 | |
852 /** | |
853 * Initializes the status subsystem. | |
854 */ | |
855 void gaim_statuses_init(void); | |
856 | |
857 /** | |
858 * Uninitializes the status subsystem. | |
859 */ | |
860 void gaim_statuses_uninit(void); | |
861 | |
862 /** | |
863 * Syncs status information to the file. | |
864 */ | |
865 void gaim_statuses_sync(void); | |
866 | |
867 /** | |
868 * Syncs status information from a file. | |
869 */ | |
870 void gaim_statuses_load(void); | |
871 | |
872 /*@}*/ | |
873 | |
874 #endif /* _GAIM_STATUS_H_ */ |