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