Mercurial > pidgin.yaz
annotate src/status.h @ 10070:2b6bf836c6b9
[gaim-migrate @ 11046]
This should fix Gideon N. Guillen's blank system message problem.
I'm getting married tomorrow. Don't expect a lot of patches out of me.
committer: Tailor Script <tailor@pidgin.im>
author | Tim Ringenbach <marv@pidgin.im> |
---|---|
date | Wed, 29 Sep 2004 15:01:33 +0000 |
parents | 39142bdd5ba6 |
children | af06746954de |
rev | line source |
---|---|
9944 | 1 /** |
2 * @file status.h Status API | |
3 * @ingroup core | |
4 * | |
6065 | 5 * gaim |
6 * | |
8046 | 7 * Gaim is the legal property of its developers, whose names are too numerous |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
9944 | 10 * |
6065 | 11 * This program is free software; you can redistribute it and/or modify |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
9944 | 25 #ifndef _GAIM_STATUS_H_ |
26 #define _GAIM_STATUS_H_ | |
6065 | 27 |
9944 | 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 /** | |
10067 | 249 * Returns whether or not the status type is exlusive. |
250 * | |
251 * @param status_type The status type. | |
252 * | |
253 * @return TRUE if the status type is exclusive, FALSE otherwise. | |
254 */ | |
255 gboolean gaim_status_type_is_exclusive(const GaimStatusType *status_type); | |
256 | |
257 /** | |
9944 | 258 * Returns whether or not a status type is available. |
259 * | |
260 * Available status types are online and possibly hidden, but not away. | |
261 * | |
262 * @param status_type The status type. | |
263 * | |
264 * @return TRUE if the status is available, or FALSE otherwise. | |
265 */ | |
266 gboolean gaim_status_type_is_available(const GaimStatusType *status_type); | |
267 | |
268 /** | |
269 * Returns a status type's primary attribute ID. | |
270 * | |
271 * @param type The status type. | |
272 * | |
273 * @return The primary attribute's ID. | |
274 */ | |
275 const char *gaim_status_type_get_primary_attr(const GaimStatusType *type); | |
276 | |
277 /** | |
278 * Returns the attribute with the specified ID. | |
279 * | |
280 * @param status_type The status type containing the attribute. | |
281 * @param id The ID of the desired attribute. | |
282 * | |
283 * @return The attribute, if found. NULL otherwise. | |
284 */ | |
285 GaimStatusAttr *gaim_status_type_get_attr(const GaimStatusType *status_type, | |
286 const char *id); | |
287 | |
288 /** | |
289 * Returns a list of all attributes in a status type. | |
290 * | |
291 * @param status_type The status type. | |
292 * | |
293 * @return The list of attributes. | |
294 */ | |
295 const GList *gaim_status_type_get_attrs(const GaimStatusType *status_type); | |
296 | |
297 /*@}*/ | |
298 | |
299 /**************************************************************************/ | |
300 /** @name GaimStatusAttr API */ | |
301 /**************************************************************************/ | |
302 /*@{*/ | |
303 | |
304 /** | |
305 * Creates a new status attribute. | |
306 * | |
307 * @param id The ID of the attribute. | |
308 * @param name The name presented to the user. | |
309 * @param value_type The type of data contained in the attribute. | |
310 * | |
311 * @return A new status attribute. | |
312 */ | |
313 GaimStatusAttr *gaim_status_attr_new(const char *id, const char *name, | |
314 GaimValue *value_type); | |
315 | |
316 /** | |
317 * Destroys a status attribute. | |
318 * | |
319 * @param attr The status attribute to destroy. | |
320 */ | |
321 void gaim_status_attr_destroy(GaimStatusAttr *attr); | |
322 | |
323 /** | |
324 * Returns the ID of a status attribute. | |
325 * | |
326 * @param attr The status attribute. | |
327 * | |
328 * @return The status attribute's ID. | |
329 */ | |
330 const char *gaim_status_attr_get_id(const GaimStatusAttr *attr); | |
331 | |
332 /** | |
333 * Returns the name of a status attribute. | |
334 * | |
335 * @param attr The status attribute. | |
336 * | |
337 * @return The status attribute's name. | |
338 */ | |
339 const char *gaim_status_attr_get_name(const GaimStatusAttr *attr); | |
340 | |
341 /** | |
342 * Returns the value type of a status attribute. | |
343 * | |
344 * @param attr The status attribute. | |
345 * | |
346 * @return The status attribute's value type. | |
347 */ | |
348 GaimValue *gaim_status_attr_get_value_type(const GaimStatusAttr *attr); | |
349 | |
350 /*@}*/ | |
351 | |
352 /**************************************************************************/ | |
353 /** @name GaimStatus API */ | |
354 /**************************************************************************/ | |
355 /*@{*/ | |
356 | |
357 /** | |
358 * Creates a new status. | |
359 * | |
360 * @param status_type The type of status. | |
361 * @param presence The parent presence. | |
362 * | |
363 * @return The new status. | |
364 */ | |
365 GaimStatus *gaim_status_new(GaimStatusType *status_type, | |
366 GaimPresence *presence); | |
367 | |
368 /** | |
369 * Destroys a status. | |
370 * | |
371 * @param status The status to destroy. | |
372 */ | |
373 void gaim_status_destroy(GaimStatus *status); | |
374 | |
375 /** | |
376 * Sets whether or not a status is active. | |
377 * | |
378 * This should only be called by the account, conversation, and buddy APIs. | |
379 * | |
380 * @param status The status. | |
381 * @param active The active state. | |
382 */ | |
383 void gaim_status_set_active(GaimStatus *status, gboolean active); | |
384 | |
385 /** | |
386 * Sets the boolean value of an attribute in a status with the specified ID. | |
387 * | |
388 * @param status The status. | |
389 * @param id The attribute ID. | |
390 * @param value The boolean value. | |
391 */ | |
392 void gaim_status_set_attr_boolean(GaimStatus *status, const char *id, | |
393 gboolean value); | |
394 | |
395 /** | |
396 * Sets the integer value of an attribute in a status with the specified ID. | |
397 * | |
398 * @param status The status. | |
399 * @param id The attribute ID. | |
400 * @param value The integer value. | |
401 */ | |
402 void gaim_status_set_attr_int(GaimStatus *status, const char *id, | |
403 int value); | |
404 | |
405 /** | |
406 * Sets the string value of an attribute in a status with the specified ID. | |
407 * | |
408 * @param status The status. | |
409 * @param id The attribute ID. | |
410 * @param value The string value. | |
411 */ | |
412 void gaim_status_set_attr_string(GaimStatus *status, const char *id, | |
413 const char *value); | |
414 | |
415 /** | |
416 * Returns the status's type. | |
417 * | |
418 * @param status The status. | |
419 * | |
420 * @return The status's type. | |
421 */ | |
422 GaimStatusType *gaim_status_get_type(const GaimStatus *status); | |
423 | |
424 /** | |
425 * Returns the status's presence. | |
426 * | |
427 * @param status The status. | |
428 * | |
429 * @return The status's presence. | |
430 */ | |
431 GaimPresence *gaim_status_get_presence(const GaimStatus *status); | |
432 | |
433 /** | |
434 * Returns the status's type ID. | |
435 * | |
436 * This is a convenience method for | |
437 * gaim_status_type_get_id(gaim_status_get_type(status)). | |
438 * | |
439 * @param status The status. | |
440 * | |
441 * @return The status's ID. | |
442 */ | |
443 const char *gaim_status_get_id(const GaimStatus *status); | |
444 | |
445 /** | |
446 * Returns the status's name. | |
447 * | |
448 * This is a convenience method for | |
449 * gaim_status_type_get_name(gaim_status_get_type(status)). | |
450 * | |
451 * @param status The status. | |
452 * | |
453 * @return The status's name. | |
454 */ | |
455 const char *gaim_status_get_name(const GaimStatus *status); | |
456 | |
457 /** | |
458 * Returns whether or not a status is independent. | |
459 * | |
460 * This is a convenience method for | |
461 * gaim_status_type_is_independent(gaim_status_get_type(status)). | |
462 * | |
463 * @param status The status. | |
464 * | |
465 * @return TRUE if the status is independent, or FALSE otherwise. | |
466 */ | |
467 gboolean gaim_status_is_independent(const GaimStatus *status); | |
468 | |
469 /** | |
10067 | 470 * Returns whether or not a status is exclusive. |
471 * | |
472 * This is a convenience method for | |
473 * gaim_status_type_is_exclusive(gaim_status_get_type(status)). | |
474 * | |
475 * @param status The status. | |
476 * | |
477 * @return TRUE if the status is exclusive, FALSE otherwise. | |
478 */ | |
479 gboolean gaim_status_is_exclusive(const GaimStatus *status); | |
480 | |
481 /** | |
9944 | 482 * Returns whether or not a status is available. |
483 * | |
484 * Available statuses are online and possibly hidden, but not away or idle. | |
485 * | |
486 * This is a convenience method for | |
487 * gaim_status_type_is_available(gaim_status_get_type(status)). | |
488 * | |
489 * @param status The status. | |
490 * | |
491 * @return TRUE if the status is available, or FALSE otherwise. | |
492 */ | |
493 gboolean gaim_status_is_available(const GaimStatus *status); | |
494 | |
495 /** | |
496 * Returns the active state of a status. | |
497 * | |
498 * @param status The status. | |
499 * | |
500 * @return The active state of the status. | |
501 */ | |
502 gboolean gaim_status_is_active(const GaimStatus *status); | |
503 | |
504 /** | |
10040
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
505 * Returns whether or not a status is considered 'online' |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
506 * |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
507 * @param status The status. |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
508 * |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
509 * @return TRUE if the status is considered online, FALSE otherwise |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
510 */ |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
511 gboolean gaim_status_is_online(const GaimStatus *status); |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
512 |
81059dce3aed
[gaim-migrate @ 10999]
Luke Schierer <lschiere@pidgin.im>
parents:
10006
diff
changeset
|
513 /** |
9944 | 514 * Returns the value of an attribute in a status with the specified ID. |
515 * | |
516 * @param status The status. | |
517 * @param id The attribute ID. | |
518 * | |
519 * @return The value of the attribute. | |
520 */ | |
521 GaimValue *gaim_status_get_attr_value(const GaimStatus *status, | |
522 const char *id); | |
523 | |
524 /** | |
525 * Returns the boolean value of an attribute in a status with the specified ID. | |
526 * | |
527 * @param status The status. | |
528 * @param id The attribute ID. | |
529 * | |
530 * @return The boolean value of the attribute. | |
531 */ | |
532 gboolean gaim_status_get_attr_boolean(const GaimStatus *status, | |
533 const char *id); | |
534 | |
535 /** | |
536 * Returns the integer value of an attribute in a status with the specified ID. | |
537 * | |
538 * @param status The status. | |
539 * @param id The attribute ID. | |
540 * | |
541 * @return The integer value of the attribute. | |
542 */ | |
543 int gaim_status_get_attr_int(const GaimStatus *status, const char *id); | |
544 | |
545 /** | |
546 * Returns the string value of an attribute in a status with the specified ID. | |
547 * | |
548 * @param status The status. | |
549 * @param id The attribute ID. | |
550 * | |
551 * @return The string value of the attribute. | |
552 */ | |
553 const char *gaim_status_get_attr_string(const GaimStatus *status, | |
554 const char *id); | |
555 | |
556 /** | |
557 * Compares two statuses for availability. | |
558 * | |
559 * @param status1 The first status. | |
560 * @param status2 The second status. | |
561 * | |
562 * @return -1 if @a status1 is more available than @a status2. | |
563 * 0 if @a status1 is equal to @a status2. | |
564 * 1 if @a status2 is more available than @a status1. | |
565 */ | |
566 gint gaim_status_compare(const GaimStatus *status1, const GaimStatus *status2); | |
567 | |
568 /*@}*/ | |
569 | |
570 /**************************************************************************/ | |
571 /** @name GaimPresence API */ | |
572 /**************************************************************************/ | |
573 /*@{*/ | |
574 | |
575 /** | |
576 * Creates a new presence. | |
577 * | |
578 * @param context The presence context. | |
579 * | |
580 * @return A new presence. | |
581 */ | |
582 GaimPresence *gaim_presence_new(GaimPresenceContext context); | |
583 | |
584 /** | |
585 * Creates a presence for an account. | |
586 * | |
587 * @param account The account. | |
588 * | |
589 * @return The new presence. | |
590 */ | |
591 GaimPresence *gaim_presence_new_for_account(GaimAccount *account); | |
592 | |
593 /** | |
594 * Creates a presence for a conversation. | |
595 * | |
596 * @param conv The conversation. | |
597 * | |
598 * @return The new presence. | |
599 */ | |
600 GaimPresence *gaim_presence_new_for_conv(GaimConversation *conv); | |
601 | |
602 /** | |
603 * Creates a presence for a buddy. | |
604 * | |
605 * @param buddy The buddy. | |
606 * | |
607 * @return The new presence. | |
608 */ | |
609 GaimPresence *gaim_presence_new_for_buddy(GaimBuddy *buddy); | |
610 | |
611 /** | |
612 * Destroys a presence. | |
613 * | |
614 * All statuses added to this list will be destroyed along with | |
615 * the presence. | |
616 * | |
617 * If this presence belongs to a buddy, you must call | |
618 * gaim_presence_remove_buddy() first. | |
619 * | |
620 * @param presence The presence to destroy. | |
621 */ | |
622 void gaim_presence_destroy(GaimPresence *presence); | |
623 | |
624 /** | |
625 * Removes a buddy from a presence. | |
626 * | |
627 * This must be done before destroying a buddy in a presence. | |
628 * | |
629 * @param presence The presence. | |
630 * @param buddy The buddy. | |
631 */ | |
632 void gaim_presence_remove_buddy(GaimPresence *presence, GaimBuddy *buddy); | |
633 | |
634 /** | |
635 * Adds a status to a presence. | |
636 * | |
637 * @param presence The presence. | |
638 * @param status The status to add. | |
639 */ | |
640 void gaim_presence_add_status(GaimPresence *presence, GaimStatus *status); | |
641 | |
642 /** | |
643 * Adds a list of statuses to the presence. | |
644 * | |
645 * @param presence The presence. | |
646 * @param source_list The source list of statuses to add. | |
647 */ | |
648 void gaim_presence_add_list(GaimPresence *presence, const GList *source_list); | |
649 | |
650 /** | |
651 * Sets the active state of a status in a presence. | |
652 * | |
653 * Only independent statuses can be set unactive. Normal statuses can only | |
654 * be set active, so if you wish to disable a status, set another | |
655 * non-independent status to active, or use gaim_presence_switch_status(). | |
656 * | |
657 * @param presence The presence. | |
658 * @param status_id The ID of the status. | |
659 * @param active The active state. | |
660 */ | |
661 void gaim_presence_set_status_active(GaimPresence *presence, | |
662 const char *status_id, gboolean active); | |
663 | |
664 /** | |
665 * Switches the active status in a presence. | |
666 * | |
667 * This is similar to gaim_presence_set_status_active(), except it won't | |
668 * activate independent statuses. | |
669 * | |
670 * @param presence The presence. | |
671 * @param status_id The status ID to switch to. | |
672 */ | |
673 void gaim_presence_switch_status(GaimPresence *presence, | |
674 const char *status_id); | |
675 | |
676 /** | |
677 * Sets the idle state and time on a presence. | |
678 * | |
679 * @param presence The presence. | |
680 * @param idle The idle state. | |
681 * @param idle_time The idle time, if @a idle is TRUE. | |
682 */ | |
683 void gaim_presence_set_idle(GaimPresence *presence, gboolean idle, | |
684 time_t idle_time); | |
685 | |
686 /** | |
10006 | 687 * Sets the login time on a presence. |
688 * | |
689 * @param presence The presence. | |
690 * @param level The login time. | |
691 */ | |
692 void gaim_presence_set_login_time(GaimPresence *presence, time_t login_time); | |
693 | |
694 /** | |
9944 | 695 * Sets the warning level on a presence. |
696 * | |
697 * @param presence The presence. | |
9978 | 698 * @param level The warning level. An integer between 0 and 100 |
699 * (inclusive) representing the percentage warned. | |
9944 | 700 */ |
701 void gaim_presence_set_warning_level(GaimPresence *presence, | |
702 unsigned int level); | |
703 | |
704 /** | |
705 * Returns the presence's context. | |
706 * | |
707 * @param presence The presence. | |
708 * | |
709 * @return The presence's context. | |
710 */ | |
711 GaimPresenceContext gaim_presence_get_context(const GaimPresence *presence); | |
712 | |
713 /** | |
714 * Returns a presence's account. | |
715 * | |
716 * @param presence The presence. | |
717 * | |
718 * @return The presence's account. | |
719 */ | |
720 GaimAccount *gaim_presence_get_account(const GaimPresence *presence); | |
721 | |
722 /** | |
723 * Returns a presence's conversation. | |
724 * | |
725 * @param presence The presence. | |
726 * | |
727 * @return The presence's conversation. | |
728 */ | |
729 GaimConversation *gaim_presence_get_conversation(const GaimPresence *presence); | |
730 | |
731 /** | |
732 * Returns a presence's chat user. | |
733 * | |
734 * @param presence The presence. | |
735 * | |
736 * @return The chat's user. | |
737 */ | |
738 const char *gaim_presence_get_chat_user(const GaimPresence *presence); | |
739 | |
740 /** | |
741 * Returns a presence's list of buddies. | |
742 * | |
743 * @param presence The presence. | |
744 * | |
745 * @return The presence's list of buddies. | |
746 */ | |
747 const GList *gaim_presence_get_buddies(const GaimPresence *presence); | |
748 | |
749 /** | |
750 * Returns all the statuses in a presence. | |
751 * | |
752 * @param presence The presence. | |
753 * | |
754 * @return The statuses. | |
755 */ | |
756 const GList *gaim_presence_get_statuses(const GaimPresence *presence); | |
757 | |
758 /** | |
759 * Returns the status with the specified ID from a presence. | |
760 * | |
761 * @param presence The presence. | |
762 * @param status_id The ID of the status. | |
763 * | |
764 * @return The status if found, or NULL. | |
765 */ | |
766 GaimStatus *gaim_presence_get_status(const GaimPresence *presence, | |
767 const char *status_id); | |
768 | |
769 /** | |
770 * Returns the active exclusive status from a presence. | |
771 * | |
772 * @param presence The presence. | |
773 * | |
774 * @return The active exclusive status. | |
775 */ | |
776 GaimStatus *gaim_presence_get_active_status(const GaimPresence *presence); | |
777 | |
778 /** | |
779 * Returns whether or not a presence is available. | |
780 * | |
781 * Available presences are online and possibly hidden, but not away or idle. | |
782 * | |
783 * @param presence The presence. | |
784 * | |
785 * @return TRUE if the presence is available, or FALSE otherwise. | |
786 */ | |
787 gboolean gaim_presence_is_available(const GaimPresence *presence); | |
788 | |
789 /** | |
790 * Returns whether or not a presence is online. | |
791 * | |
792 * @param presence The presence. | |
793 * | |
794 * @return TRUE if the presence is online, or FALSE otherwise. | |
795 */ | |
796 gboolean gaim_presence_is_online(const GaimPresence *presence); | |
797 | |
798 /** | |
799 * Returns whether or not a status in a presence is active. | |
800 * | |
801 * A status is active if itself or any of its sub-statuses are active. | |
802 * | |
803 * @param presence The presence. | |
804 * @param status_id The ID of the status. | |
805 * | |
806 * @return TRUE if the status is active, or FALSE. | |
807 */ | |
808 gboolean gaim_presence_is_status_active(const GaimPresence *presence, | |
809 const char *status_id); | |
810 | |
811 /** | |
812 * Returns whether or not a status with the specified primitive type | |
813 * in a presence is active. | |
814 * | |
815 * A status is active if itself or any of its sub-statuses are active. | |
816 * | |
817 * @param presence The presence. | |
818 * @param primitive The status primitive. | |
819 * | |
820 * @return TRUE if the status is active, or FALSE. | |
821 */ | |
822 gboolean gaim_presence_is_status_primitive_active( | |
823 const GaimPresence *presence, GaimStatusPrimitive primitive); | |
824 | |
825 /** | |
826 * Returns whether or not a presence is idle. | |
827 * | |
828 * @param presence The presence. | |
829 * | |
830 * @return TRUE if the presence is idle, or FALSE otherwise. | |
831 */ | |
832 gboolean gaim_presence_is_idle(const GaimPresence *presence); | |
833 | |
834 /** | |
835 * Returns the presence's idle time. | |
836 * | |
837 * @param presence The presence. | |
838 * | |
839 * @return The presence's idle time. | |
840 */ | |
841 time_t gaim_presence_get_idle_time(const GaimPresence *presence); | |
842 | |
843 /** | |
844 * Returns the presence's warning level. | |
845 * | |
846 * @param presence The presence. | |
847 * | |
848 * @return The presence's warning level. | |
849 */ | |
850 unsigned int gaim_presence_get_warning_level(const GaimPresence *presence); | |
851 | |
852 /** | |
853 * Compares two presences for availability. | |
854 * | |
855 * @param presence1 The first presence. | |
856 * @param presence2 The second presence. | |
857 * | |
858 * @return -1 if @a presence1 is less available than @a presence2. | |
859 * 0 if @a presence1 is equal to @a presence2. | |
860 * 1 if @a presence2 is more available than @a presence1. | |
861 */ | |
862 gint gaim_presence_compare(const GaimPresence *presence1, | |
863 const GaimPresence *presence2); | |
864 | |
865 /*@}*/ | |
866 | |
867 | |
868 /**************************************************************************/ | |
869 /** @name Status subsystem */ | |
870 /**************************************************************************/ | |
871 /*@{*/ | |
872 | |
873 /** | |
874 * Returns all stored statuses. | |
875 * | |
876 * @return A list of stored statuses. | |
877 */ | |
878 const GList *gaim_statuses_get_stored(void); | |
879 | |
880 /** | |
881 * Finds a stored status with the specified status type and primary ID. | |
882 * | |
883 * @param status_type The status type of the status. | |
884 * @param id The primary attribute ID. | |
885 * | |
886 * @return The stored status if found, or NULL. | |
887 */ | |
888 GaimStatus *gaim_statuses_find_stored(const GaimStatusType *status_type, | |
889 const char *id); | |
890 | |
891 /** | |
892 * Initializes the status subsystem. | |
893 */ | |
894 void gaim_statuses_init(void); | |
895 | |
896 /** | |
897 * Uninitializes the status subsystem. | |
898 */ | |
899 void gaim_statuses_uninit(void); | |
900 | |
901 /** | |
902 * Syncs status information to the file. | |
903 */ | |
904 void gaim_statuses_sync(void); | |
905 | |
906 /** | |
907 * Syncs status information from a file. | |
908 */ | |
909 void gaim_statuses_load(void); | |
910 | |
911 /*@}*/ | |
912 | |
913 #endif /* _GAIM_STATUS_H_ */ |