Mercurial > pidgin
annotate libgaim/savedstatuses.h @ 15080:d24de6319f87
[gaim-migrate @ 17866]
Get rid of a bunch of compile warnings
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Fri, 01 Dec 2006 08:07:17 +0000 |
parents | 8d9a473bbab9 |
children |
rev | line source |
---|---|
14192 | 1 /** |
2 * @file savedstatuses.h Saved Status API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
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. | |
10 * | |
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 */ | |
25 #ifndef _GAIM_SAVEDSTATUSES_H_ | |
26 #define _GAIM_SAVEDSTATUSES_H_ | |
27 | |
28 /** | |
29 * Saved statuses don't really interact much with the rest of Gaim. It | |
30 * could really be a plugin. It's just a list of away states. When | |
31 * a user chooses one of the saved states, their Gaim accounts are set | |
32 * to the settings of that state. | |
33 * | |
34 * In the savedstatus API, there is the concept of a 'transient' | |
35 * saved status. A transient saved status is one that is not | |
36 * permanent. Gaim will removed it automatically if it isn't | |
37 * used for a period of time. Transient saved statuses don't | |
38 * have titles and they don't show up in the list of saved | |
39 * statuses. In fact, if a saved status does not have a title | |
40 * then it is transient. If it does have a title, then it is not | |
41 * transient. | |
42 * | |
43 * What good is a transient status, you ask? They can be used to | |
44 * keep track of the user's 5 most recently used statuses, for | |
45 * example. Basically if they just set a message on the fly, | |
46 * we'll cache it for them in case they want to use it again. If | |
47 * they don't use it again, we'll just delete it. | |
48 */ | |
49 | |
50 /* | |
51 * TODO: Hmm. We should probably just be saving GaimPresences. That's | |
52 * something we should look into once the status box gets fleshed | |
53 * out more. | |
54 */ | |
55 | |
56 typedef struct _GaimSavedStatus GaimSavedStatus; | |
57 typedef struct _GaimSavedStatusSub GaimSavedStatusSub; | |
58 | |
59 #include "status.h" | |
60 | |
14925
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
61 #ifdef __cplusplus |
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
62 extern "C" { |
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
63 #endif |
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
64 |
14192 | 65 /**************************************************************************/ |
66 /** @name Saved status subsystem */ | |
67 /**************************************************************************/ | |
68 /*@{*/ | |
69 | |
70 /** | |
71 * Create a new saved status. This will add the saved status to the | |
72 * list of saved statuses and writes the revised list to status.xml. | |
73 * | |
74 * @param title The title of the saved status. This must be | |
75 * unique. Or, if you want to create a transient | |
76 * saved status, then pass in NULL. | |
77 * @param type The type of saved status. | |
78 * | |
79 * @return The newly created saved status, or NULL if the title you | |
80 * used was already taken. | |
81 */ | |
82 GaimSavedStatus *gaim_savedstatus_new(const char *title, | |
83 GaimStatusPrimitive type); | |
84 | |
85 /** | |
86 * Set the title for the given saved status. | |
87 * | |
88 * @param status The saved status. | |
89 * @param title The title of the saved status. | |
90 */ | |
91 void gaim_savedstatus_set_title(GaimSavedStatus *status, | |
92 const char *title); | |
93 | |
94 /** | |
95 * Set the type for the given saved status. | |
96 * | |
97 * @param status The saved status. | |
98 * @param type The type of saved status. | |
99 */ | |
100 void gaim_savedstatus_set_type(GaimSavedStatus *status, | |
101 GaimStatusPrimitive type); | |
102 | |
103 /** | |
104 * Set the message for the given saved status. | |
105 * | |
106 * @param status The saved status. | |
107 * @param message The message, or NULL if you want to unset the | |
108 * message for this status. | |
109 */ | |
110 void gaim_savedstatus_set_message(GaimSavedStatus *status, | |
111 const char *message); | |
112 | |
113 /** | |
114 * Set a substatus for an account in a saved status. | |
115 * | |
116 * @param status The saved status. | |
117 * @param account The account. | |
118 * @param type The status type for the account in the staved | |
119 * status. | |
120 * @param message The message for the account in the substatus. | |
121 */ | |
122 void gaim_savedstatus_set_substatus(GaimSavedStatus *status, | |
123 const GaimAccount *account, | |
124 const GaimStatusType *type, | |
125 const char *message); | |
126 | |
127 /** | |
128 * Unset a substatus for an account in a saved status. This clears | |
129 * the previosly set substatus for the GaimSavedStatus. If this | |
130 * saved status is activated then this account will use the default | |
131 * status type and message. | |
132 * | |
133 * @param saved_status The saved status. | |
134 * @param account The account. | |
135 */ | |
136 void gaim_savedstatus_unset_substatus(GaimSavedStatus *saved_status, | |
137 const GaimAccount *account); | |
138 | |
139 /** | |
140 * Delete a saved status. This removes the saved status from the list | |
141 * of saved statuses, and writes the revised list to status.xml. | |
142 * | |
143 * @param title The title of the saved status. | |
144 * | |
145 * @return TRUE if the status was successfully deleted. FALSE if the | |
146 * status could not be deleted because no saved status exists | |
147 * with the given title. | |
148 */ | |
149 gboolean gaim_savedstatus_delete(const char *title); | |
150 | |
151 /** | |
152 * Returns all saved statuses. | |
153 * | |
154 * @return A list of saved statuses. | |
155 */ | |
156 const GList *gaim_savedstatuses_get_all(void); | |
157 | |
158 /** | |
159 * Returns the n most popular saved statuses. "Popularity" is | |
160 * determined by when the last time a saved_status was used and | |
161 * how many times it has been used. If the current status would | |
162 * normally show up in this list, then it is omited and instead | |
163 * the "how_many+1" saved status will appear in the list. Also | |
164 * transient statuses without messages are not included in the | |
165 * list. | |
166 * | |
167 * @param how_many The maximum number of saved statuses | |
168 * to return, or '0' to get all saved | |
169 * statuses sorted by popularity. | |
170 * @return A linked list containing at most how_many | |
171 * GaimSavedStatuses. This list should be | |
172 * g_list_free'd by the caller (but the | |
173 * GaimSavedStatuses must not be free'd). | |
174 */ | |
175 GList *gaim_savedstatuses_get_popular(unsigned int how_many); | |
176 | |
177 /** | |
178 * Returns the currently selected saved status. If we are idle | |
179 * then this returns gaim_savedstatus_get_idleaway(). Otherwise | |
180 * it returns gaim_savedstatus_get_default(). | |
181 * | |
182 * @return A pointer to the in-use GaimSavedStatus. | |
183 * This function never returns NULL. | |
184 */ | |
185 GaimSavedStatus *gaim_savedstatus_get_current(void); | |
186 | |
187 /** | |
188 * Returns the default saved status that is used when our | |
189 * accounts are not idle-away. | |
190 * | |
191 * @return A pointer to the in-use GaimSavedStatus. | |
192 * This function never returns NULL. | |
193 */ | |
194 GaimSavedStatus *gaim_savedstatus_get_default(void); | |
195 | |
196 /** | |
197 * Returns the saved status that is used when your | |
198 * accounts become idle-away. | |
199 * | |
200 * @return A pointer to the idle-away GaimSavedStatus. | |
201 * This function never returns NULL. | |
202 */ | |
203 GaimSavedStatus *gaim_savedstatus_get_idleaway(void); | |
204 | |
205 /** | |
206 * Return TRUE if we are currently idle-away. Otherwise | |
207 * returns FALSE. | |
208 * | |
209 * @return TRUE if our accounts have been set to idle-away. | |
210 */ | |
211 gboolean gaim_savedstatus_is_idleaway(void); | |
212 | |
213 /** | |
214 * Set whether accounts in Gaim are idle-away or not. | |
215 * | |
216 * @param TRUE if accounts should be switched to use the | |
217 * idle-away saved status. FALSE if they should | |
218 * be switched to use the default status. | |
219 */ | |
220 void gaim_savedstatus_set_idleaway(gboolean idleaway); | |
221 | |
222 /** | |
223 * Returns the status to be used when gaim is starting up | |
224 * | |
225 * @return A pointer to the startup GaimSavedStatus. | |
226 * This function never returns NULL. | |
227 */ | |
228 GaimSavedStatus *gaim_savedstatus_get_startup(void); | |
229 | |
230 /** | |
231 * Finds a saved status with the specified title. | |
232 * | |
233 * @param title The name of the saved status. | |
234 * | |
235 * @return The saved status if found, or NULL. | |
236 */ | |
237 GaimSavedStatus *gaim_savedstatus_find(const char *title); | |
238 | |
239 /** | |
240 * Finds a saved status with the specified creation time. | |
241 * | |
242 * @param creation_time The timestamp when the saved | |
243 * status was created. | |
244 * | |
245 * @return The saved status if found, or NULL. | |
246 */ | |
247 GaimSavedStatus *gaim_savedstatus_find_by_creation_time(time_t creation_time); | |
248 | |
249 /** | |
250 * Finds a saved status with the specified primitive and message. | |
251 * | |
252 * @param type The GaimStatusPrimitive for the status you're trying | |
253 * to find. | |
254 * @param message The message for the status you're trying | |
255 * to find. | |
256 * | |
257 * @return The saved status if found, or NULL. | |
258 */ | |
259 GaimSavedStatus *gaim_savedstatus_find_transient_by_type_and_message(GaimStatusPrimitive type, const char *message); | |
260 | |
261 /** | |
262 * Determines if a given saved status is "transient." | |
263 * A transient saved status is one that was not | |
264 * explicitly added by the user. Transient statuses | |
265 * are automatically removed if they are not used | |
266 * for a period of time. | |
267 * | |
268 * A transient saved statuses is automatically | |
269 * created by the status box when the user sets himself | |
270 * to one of the generic primitive statuses. The reason | |
271 * we need to save this status information is so we can | |
272 * restore it when Gaim restarts. | |
273 * | |
274 * @param saved_status The saved status. | |
275 * | |
276 * @return TRUE if the saved status is transient. | |
277 */ | |
278 gboolean gaim_savedstatus_is_transient(const GaimSavedStatus *saved_status); | |
279 | |
280 /** | |
281 * Return the name of a given saved status. | |
282 * | |
283 * @param saved_status The saved status. | |
284 * | |
285 * @return The title. This value may be a static buffer which may | |
286 * be overwritten on subsequent calls to this function. If | |
287 * you need a reference to the title for prolonged use then | |
288 * you should make a copy of it. | |
289 */ | |
290 const char *gaim_savedstatus_get_title(const GaimSavedStatus *saved_status); | |
291 | |
292 /** | |
293 * Return the type of a given saved status. | |
294 * | |
295 * @param saved_status The saved status. | |
296 * | |
297 * @return The name. | |
298 */ | |
299 GaimStatusPrimitive gaim_savedstatus_get_type(const GaimSavedStatus *saved_status); | |
300 | |
301 /** | |
302 * Return the default message of a given saved status. | |
303 * | |
304 * @param saved_status The saved status. | |
305 * | |
306 * @return The message. This will return NULL if the saved | |
307 * status does not have a message. This will | |
308 * contain the normal markup that is created by | |
309 * Gaim's IMHTML (basically HTML markup). | |
310 */ | |
311 const char *gaim_savedstatus_get_message(const GaimSavedStatus *saved_status); | |
312 | |
313 /** | |
314 * Return the time in seconds-since-the-epoch when this | |
315 * saved status was created. Note: For any status created | |
316 * by Gaim 1.5.0 or older this value will be invalid and | |
317 * very small (close to 0). This is because Gaim 1.5.0 | |
318 * and older did not record the timestamp when the status | |
319 * was created. | |
320 * | |
321 * However, this value is guaranteed to be a unique | |
322 * identifier for the given saved status. | |
323 * | |
324 * @param saved_status The saved status. | |
325 * | |
326 * @return The timestamp when this saved status was created. | |
327 */ | |
328 time_t gaim_savedstatus_get_creation_time(const GaimSavedStatus *saved_status); | |
329 | |
330 /** | |
331 * Determine if a given saved status has "substatuses," | |
332 * or if it is a simple status (the same for all | |
333 * accounts). | |
334 * | |
335 * @param saved_status The saved status. | |
336 * | |
337 * @return TRUE if the saved_status has substatuses. | |
338 * FALSE otherwise. | |
339 */ | |
340 gboolean gaim_savedstatus_has_substatuses(const GaimSavedStatus *saved_status); | |
341 | |
342 /** | |
343 * Get the substatus for an account in a saved status. | |
344 * | |
345 * @param saved_status The saved status. | |
346 * @param account The account. | |
347 * | |
348 * @return The GaimSavedStatusSub for the account, or NULL if | |
349 * the given account does not have a substatus that | |
350 * differs from the default status of this GaimSavedStatus. | |
351 */ | |
352 GaimSavedStatusSub *gaim_savedstatus_get_substatus( | |
353 const GaimSavedStatus *saved_status, | |
354 const GaimAccount *account); | |
355 | |
356 /** | |
357 * Get the status type of a given substatus. | |
358 * | |
359 * @param substatus The substatus. | |
360 * | |
361 * @return The status type. | |
362 */ | |
363 const GaimStatusType *gaim_savedstatus_substatus_get_type(const GaimSavedStatusSub *substatus); | |
364 | |
365 /** | |
366 * Get the message of a given substatus. | |
367 * | |
368 * @param substatus The substatus. | |
369 * | |
370 * @return The message of the substatus, or NULL if this substatus does | |
371 * not have a message. | |
372 */ | |
373 const char *gaim_savedstatus_substatus_get_message(const GaimSavedStatusSub *substatus); | |
374 | |
375 /** | |
376 * Sets the statuses for all your accounts to those specified | |
377 * by the given saved_status. This function calls | |
378 * gaim_savedstatus_activate_for_account() for all your accounts. | |
379 * | |
380 * @param saved_status The status you want to set your accounts to. | |
381 */ | |
382 void gaim_savedstatus_activate(GaimSavedStatus *saved_status); | |
383 | |
384 /** | |
385 * Sets the statuses for a given account to those specified | |
386 * by the given saved_status. | |
387 * | |
388 * @param saved_status The status you want to set your accounts to. | |
389 * @param account The account whose statuses you want to change. | |
390 */ | |
391 void gaim_savedstatus_activate_for_account(const GaimSavedStatus *saved_status, GaimAccount *account); | |
392 | |
393 /** | |
394 * Get the handle for the status subsystem. | |
395 * | |
396 * @return the handle to the status subsystem | |
397 */ | |
398 void *gaim_savedstatuses_get_handle(void); | |
399 | |
400 /** | |
401 * Initializes the status subsystem. | |
402 */ | |
403 void gaim_savedstatuses_init(void); | |
404 | |
405 /** | |
406 * Uninitializes the status subsystem. | |
407 */ | |
408 void gaim_savedstatuses_uninit(void); | |
409 | |
410 /*@}*/ | |
411 | |
14925
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
412 #ifdef __cplusplus |
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
413 } |
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
414 #endif |
8d9a473bbab9
[gaim-migrate @ 17697]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14192
diff
changeset
|
415 |
14192 | 416 #endif /* _GAIM_SAVEDSTATUSES_H_ */ |