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