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