comparison libpurple/savedstatuses.h @ 15373:5fe8042783c1

Rename gtk/ and libgaim/ to pidgin/ and libpurple/
author Sean Egan <seanegan@gmail.com>
date Sat, 20 Jan 2007 02:32:10 +0000
parents
children 32c366eeeb99
comparison
equal deleted inserted replaced
15372:f79e0f4df793 15373:5fe8042783c1
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
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64
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
412 #ifdef __cplusplus
413 }
414 #endif
415
416 #endif /* _GAIM_SAVEDSTATUSES_H_ */