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