Mercurial > pidgin3 / file comparison

comparison: core/savedstatuses.h

core/savedstatuses.h

changeset 14253
b63ebf84c42b
parent 14190
4d3fc3f58cc6
equal deleted inserted replaced
14252:d10dda2777a9 14253:b63ebf84c42b
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 /**************************************************************************/
62 /** @name Saved status subsystem */
63 /**************************************************************************/
64 /*@{*/
65
66 /**
67 * Create a new saved status. This will add the saved status to the
68 * list of saved statuses and writes the revised list to status.xml.
69 *
70 * @param title The title of the saved status. This must be
71 * unique. Or, if you want to create a transient
72 * saved status, then pass in NULL.
73 * @param type The type of saved status.
74 *
75 * @return The newly created saved status, or NULL if the title you
76 * used was already taken.
77 */
78 GaimSavedStatus *gaim_savedstatus_new(const char *title,
79 GaimStatusPrimitive type);
80
81 /**
82 * Set the title for the given saved status.
83 *
84 * @param status The saved status.
85 * @param title The title of the saved status.
86 */
87 void gaim_savedstatus_set_title(GaimSavedStatus *status,
88 const char *title);
89
90 /**
91 * Set the type for the given saved status.
92 *
93 * @param status The saved status.
94 * @param type The type of saved status.
95 */
96 void gaim_savedstatus_set_type(GaimSavedStatus *status,
97 GaimStatusPrimitive type);
98
99 /**
100 * Set the message for the given saved status.
101 *
102 * @param status The saved status.
103 * @param message The message, or NULL if you want to unset the
104 * message for this status.
105 */
106 void gaim_savedstatus_set_message(GaimSavedStatus *status,
107 const char *message);
108
109 /**
110 * Set a substatus for an account in a saved status.
111 *
112 * @param status The saved status.
113 * @param account The account.
114 * @param type The status type for the account in the staved
115 * status.
116 * @param message The message for the account in the substatus.
117 */
118 void gaim_savedstatus_set_substatus(GaimSavedStatus *status,
119 const GaimAccount *account,
120 const GaimStatusType *type,
121 const char *message);
122
123 /**
124 * Unset a substatus for an account in a saved status. This clears
125 * the previosly set substatus for the GaimSavedStatus. If this
126 * saved status is activated then this account will use the default
127 * status type and message.
128 *
129 * @param saved_status The saved status.
130 * @param account The account.
131 */
132 void gaim_savedstatus_unset_substatus(GaimSavedStatus *saved_status,
133 const GaimAccount *account);
134
135 /**
136 * Delete a saved status. This removes the saved status from the list
137 * of saved statuses, and writes the revised list to status.xml.
138 *
139 * @param title The title of the saved status.
140 *
141 * @return TRUE if the status was successfully deleted. FALSE if the
142 * status could not be deleted because no saved status exists
143 * with the given title.
144 */
145 gboolean gaim_savedstatus_delete(const char *title);
146
147 /**
148 * Returns all saved statuses.
149 *
150 * @return A list of saved statuses.
151 */
152 const GList *gaim_savedstatuses_get_all(void);
153
154 /**
155 * Returns the n most popular saved statuses. "Popularity" is
156 * determined by when the last time a saved_status was used and
157 * how many times it has been used. If the current status would
158 * normally show up in this list, then it is omited and instead
159 * the "how_many+1" saved status will appear in the list. Also
160 * transient statuses without messages are not included in the
161 * list.
162 *
163 * @param how_many The maximum number of saved statuses
164 * to return, or '0' to get all saved
165 * statuses sorted by popularity.
166 * @return A linked list containing at most how_many
167 * GaimSavedStatuses. This list should be
168 * g_list_free'd by the caller (but the
169 * GaimSavedStatuses must not be free'd).
170 */
171 GList *gaim_savedstatuses_get_popular(unsigned int how_many);
172
173 /**
174 * Returns the currently selected saved status. If we are idle
175 * then this returns gaim_savedstatus_get_idleaway(). Otherwise
176 * it returns gaim_savedstatus_get_default().
177 *
178 * @return A pointer to the in-use GaimSavedStatus.
179 * This function never returns NULL.
180 */
181 GaimSavedStatus *gaim_savedstatus_get_current(void);
182
183 /**
184 * Returns the default saved status that is used when our
185 * accounts are not idle-away.
186 *
187 * @return A pointer to the in-use GaimSavedStatus.
188 * This function never returns NULL.
189 */
190 GaimSavedStatus *gaim_savedstatus_get_default(void);
191
192 /**
193 * Returns the saved status that is used when your
194 * accounts become idle-away.
195 *
196 * @return A pointer to the idle-away GaimSavedStatus.
197 * This function never returns NULL.
198 */
199 GaimSavedStatus *gaim_savedstatus_get_idleaway(void);
200
201 /**
202 * Return TRUE if we are currently idle-away. Otherwise
203 * returns FALSE.
204 *
205 * @return TRUE if our accounts have been set to idle-away.
206 */
207 gboolean gaim_savedstatus_is_idleaway(void);
208
209 /**
210 * Set whether accounts in Gaim are idle-away or not.
211 *
212 * @param TRUE if accounts should be switched to use the
213 * idle-away saved status. FALSE if they should
214 * be switched to use the default status.
215 */
216 void gaim_savedstatus_set_idleaway(gboolean idleaway);
217
218 /**
219 * Returns the status to be used when gaim is starting up
220 *
221 * @return A pointer to the startup GaimSavedStatus.
222 * This function never returns NULL.
223 */
224 GaimSavedStatus *gaim_savedstatus_get_startup(void);
225
226 /**
227 * Finds a saved status with the specified title.
228 *
229 * @param title The name of the saved status.
230 *
231 * @return The saved status if found, or NULL.
232 */
233 GaimSavedStatus *gaim_savedstatus_find(const char *title);
234
235 /**
236 * Finds a saved status with the specified creation time.
237 *
238 * @param creation_time The timestamp when the saved
239 * status was created.
240 *
241 * @return The saved status if found, or NULL.
242 */
243 GaimSavedStatus *gaim_savedstatus_find_by_creation_time(time_t creation_time);
244
245 /**
246 * Finds a saved status with the specified primitive and message.
247 *
248 * @param type The GaimStatusPrimitive for the status you're trying
249 * to find.
250 * @param message The message for the status you're trying
251 * to find.
252 *
253 * @return The saved status if found, or NULL.
254 */
255 GaimSavedStatus *gaim_savedstatus_find_transient_by_type_and_message(GaimStatusPrimitive type, const char *message);
256
257 /**
258 * Determines if a given saved status is "transient."
259 * A transient saved status is one that was not
260 * explicitly added by the user. Transient statuses
261 * are automatically removed if they are not used
262 * for a period of time.
263 *
264 * A transient saved statuses is automatically
265 * created by the status box when the user sets himself
266 * to one of the generic primitive statuses. The reason
267 * we need to save this status information is so we can
268 * restore it when Gaim restarts.
269 *
270 * @param saved_status The saved status.
271 *
272 * @return TRUE if the saved status is transient.
273 */
274 gboolean gaim_savedstatus_is_transient(const GaimSavedStatus *saved_status);
275
276 /**
277 * Return the name of a given saved status.
278 *
279 * @param saved_status The saved status.
280 *
281 * @return The title. This value may be a static buffer which may
282 * be overwritten on subsequent calls to this function. If
283 * you need a reference to the title for prolonged use then
284 * you should make a copy of it.
285 */
286 const char *gaim_savedstatus_get_title(const GaimSavedStatus *saved_status);
287
288 /**
289 * Return the type of a given saved status.
290 *
291 * @param saved_status The saved status.
292 *
293 * @return The name.
294 */
295 GaimStatusPrimitive gaim_savedstatus_get_type(const GaimSavedStatus *saved_status);
296
297 /**
298 * Return the default message of a given saved status.
299 *
300 * @param saved_status The saved status.
301 *
302 * @return The message. This will return NULL if the saved
303 * status does not have a message. This will
304 * contain the normal markup that is created by
305 * Gaim's IMHTML (basically HTML markup).
306 */
307 const char *gaim_savedstatus_get_message(const GaimSavedStatus *saved_status);
308
309 /**
310 * Return the time in seconds-since-the-epoch when this
311 * saved status was created. Note: For any status created
312 * by Gaim 1.5.0 or older this value will be invalid and
313 * very small (close to 0). This is because Gaim 1.5.0
314 * and older did not record the timestamp when the status
315 * was created.
316 *
317 * However, this value is guaranteed to be a unique
318 * identifier for the given saved status.
319 *
320 * @param saved_status The saved status.
321 *
322 * @return The timestamp when this saved status was created.
323 */
324 time_t gaim_savedstatus_get_creation_time(const GaimSavedStatus *saved_status);
325
326 /**
327 * Determine if a given saved status has "substatuses,"
328 * or if it is a simple status (the same for all
329 * accounts).
330 *
331 * @param saved_status The saved status.
332 *
333 * @return TRUE if the saved_status has substatuses.
334 * FALSE otherwise.
335 */
336 gboolean gaim_savedstatus_has_substatuses(const GaimSavedStatus *saved_status);
337
338 /**
339 * Get the substatus for an account in a saved status.
340 *
341 * @param saved_status The saved status.
342 * @param account The account.
343 *
344 * @return The GaimSavedStatusSub for the account, or NULL if
345 * the given account does not have a substatus that
346 * differs from the default status of this GaimSavedStatus.
347 */
348 GaimSavedStatusSub *gaim_savedstatus_get_substatus(
349 const GaimSavedStatus *saved_status,
350 const GaimAccount *account);
351
352 /**
353 * Get the status type of a given substatus.
354 *
355 * @param substatus The substatus.
356 *
357 * @return The status type.
358 */
359 const GaimStatusType *gaim_savedstatus_substatus_get_type(const GaimSavedStatusSub *substatus);
360
361 /**
362 * Get the message of a given substatus.
363 *
364 * @param substatus The substatus.
365 *
366 * @return The message of the substatus, or NULL if this substatus does
367 * not have a message.
368 */
369 const char *gaim_savedstatus_substatus_get_message(const GaimSavedStatusSub *substatus);
370
371 /**
372 * Sets the statuses for all your accounts to those specified
373 * by the given saved_status. This function calls
374 * gaim_savedstatus_activate_for_account() for all your accounts.
375 *
376 * @param saved_status The status you want to set your accounts to.
377 */
378 void gaim_savedstatus_activate(GaimSavedStatus *saved_status);
379
380 /**
381 * Sets the statuses for a given account to those specified
382 * by the given saved_status.
383 *
384 * @param saved_status The status you want to set your accounts to.
385 * @param account The account whose statuses you want to change.
386 */
387 void gaim_savedstatus_activate_for_account(const GaimSavedStatus *saved_status, GaimAccount *account);
388
389 /**
390 * Get the handle for the status subsystem.
391 *
392 * @return the handle to the status subsystem
393 */
394 void *gaim_savedstatuses_get_handle(void);
395
396 /**
397 * Initializes the status subsystem.
398 */
399 void gaim_savedstatuses_init(void);
400
401 /**
402 * Uninitializes the status subsystem.
403 */
404 void gaim_savedstatuses_uninit(void);
405
406 /*@}*/
407
408 #endif /* _GAIM_SAVEDSTATUSES_H_ */

Mercurial Repository: pidgin3

mercurial