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