Mercurial > pidgin
annotate src/savedstatuses.h @ 12924:e841e23a334c
[gaim-migrate @ 15277]
patch #1408512 Psychic popups: disable when away
committer: Tailor Script <tailor@pidgin.im>
author | Christopher O'Brien <siege@pidgin.im> |
---|---|
date | Wed, 18 Jan 2006 03:04:25 +0000 |
parents | e5f780a6137b |
children | e3b9c6c7bcf6 |
rev | line source |
---|---|
10418 | 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. | |
12125 | 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. | |
10418 | 48 */ |
49 | |
11651 | 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 | |
10419 | 56 typedef struct _GaimSavedStatus GaimSavedStatus; |
57 typedef struct _GaimSavedStatusSub GaimSavedStatusSub; | |
10418 | 58 |
10447 | 59 #include "status.h" |
60 | |
10418 | 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 * | |
11651 | 70 * @param title The title of the saved status. This must be |
12125 | 71 * unique. Or, if you want to create a transient |
72 * saved status, then pass in NULL. | |
11651 | 73 * @param type The type of saved status. |
10418 | 74 * |
10420 | 75 * @return The newly created saved status, or NULL if the title you |
76 * used was already taken. | |
10418 | 77 */ |
10419 | 78 GaimSavedStatus *gaim_savedstatus_new(const char *title, |
79 GaimStatusPrimitive type); | |
10418 | 80 |
81 /** | |
12056 | 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 /** | |
11651 | 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 /** | |
10420 | 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 /** | |
12056 | 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 */ | |
12080 | 118 void gaim_savedstatus_set_substatus(GaimSavedStatus *status, |
119 const GaimAccount *account, | |
120 const GaimStatusType *type, | |
121 const char *message); | |
12056 | 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 * | |
12245 | 129 * @param saved_status The saved status. |
130 * @param account The account. | |
12056 | 131 */ |
12080 | 132 void gaim_savedstatus_unset_substatus(GaimSavedStatus *saved_status, |
12056 | 133 const GaimAccount *account); |
134 | |
135 /** | |
10418 | 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 */ | |
10419 | 145 gboolean gaim_savedstatus_delete(const char *title); |
10418 | 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 /** | |
12688 | 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. | |
158 * | |
159 * @param how_many The maximum number of saved statuses | |
160 * to return, or '0' to get all saved | |
161 * statuses sorted by popularity. | |
162 * @return A linked list containing at most how_many | |
163 * GaimSavedStatuses. This list should be | |
164 * g_list_free'd by the caller (but the | |
165 * GaimSavedStatuses must not be free'd). | |
166 */ | |
167 GList *gaim_savedstatuses_get_popular(unsigned int how_many); | |
168 | |
169 /** | |
12125 | 170 * Returns the currently selected saved status. |
171 * | |
172 * @return A pointer to the in-use GaimSavedStatus. | |
173 */ | |
12323
fc464a0abccc
[gaim-migrate @ 14627]
Richard Laager <rlaager@wiktel.com>
parents:
12245
diff
changeset
|
174 GaimSavedStatus *gaim_savedstatus_get_current(void); |
12125 | 175 |
176 /** | |
12857
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
177 * Returns the status to be used when gaim is starting up |
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
178 * |
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
179 * @return A pointer to the startup GaimSavedStatus. |
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
180 */ |
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
181 GaimSavedStatus *gaim_savedstatus_get_startup(void); |
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
182 |
e5f780a6137b
[gaim-migrate @ 15208]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12690
diff
changeset
|
183 /** |
12125 | 184 * Returns the saved status that gets used when your |
185 * accounts become idle-away. | |
186 * | |
187 * @return A pointer to the idle-away GaimSavedStatus. | |
188 */ | |
12323
fc464a0abccc
[gaim-migrate @ 14627]
Richard Laager <rlaager@wiktel.com>
parents:
12245
diff
changeset
|
189 GaimSavedStatus *gaim_savedstatus_get_idleaway(void); |
12125 | 190 |
191 /** | |
10418 | 192 * Finds a saved status with the specified title. |
193 * | |
194 * @param title The name of the saved status. | |
195 * | |
196 * @return The saved status if found, or NULL. | |
197 */ | |
10419 | 198 GaimSavedStatus *gaim_savedstatus_find(const char *title); |
10418 | 199 |
200 /** | |
12690 | 201 * Finds a saved status with the specified creation time. |
202 * | |
203 * @param creation_time The timestamp when the saved | |
204 * status was created. | |
205 * | |
206 * @return The saved status if found, or NULL. | |
207 */ | |
208 GaimSavedStatus *gaim_savedstatus_find_by_creation_time(time_t creation_time); | |
209 | |
210 /** | |
11651 | 211 * Determines if a given saved status is "transient." |
212 * A transient saved status is one that was not | |
213 * explicitly added by the user. Transient statuses | |
214 * are automatically removed if they are not used | |
215 * for a period of time. | |
216 * | |
217 * A transient saved statuses is automatically | |
218 * created by the status box when the user sets himself | |
219 * to one of the generic primitive statuses. The reason | |
220 * we need to save this status information is so we can | |
221 * restore it when Gaim restarts. | |
222 * | |
223 * @param saved_status The saved status. | |
224 * | |
225 * @return TRUE if the saved status is transient. | |
226 */ | |
227 gboolean gaim_savedstatus_is_transient(const GaimSavedStatus *saved_status); | |
228 | |
229 /** | |
10418 | 230 * Return the name of a given saved status. |
231 * | |
232 * @param saved_status The saved status. | |
233 * | |
12690 | 234 * @return The title. This value may be a static buffer which may |
235 * be overwritten on subsequent calls to this function. If | |
236 * you need a reference to the title for prolonged use then | |
237 * you should make a copy of it. | |
10418 | 238 */ |
10419 | 239 const char *gaim_savedstatus_get_title(const GaimSavedStatus *saved_status); |
10418 | 240 |
241 /** | |
12056 | 242 * Return the type of a given saved status. |
10418 | 243 * |
244 * @param saved_status The saved status. | |
245 * | |
246 * @return The name. | |
247 */ | |
10419 | 248 GaimStatusPrimitive gaim_savedstatus_get_type(const GaimSavedStatus *saved_status); |
10418 | 249 |
250 /** | |
12056 | 251 * Return the default message of a given saved status. |
10418 | 252 * |
253 * @param saved_status The saved status. | |
254 * | |
255 * @return The name. | |
256 */ | |
10419 | 257 const char *gaim_savedstatus_get_message(const GaimSavedStatus *saved_status); |
10418 | 258 |
259 /** | |
12125 | 260 * Return the time in seconds-since-the-epoch when this |
261 * saved status was created. Note: For any status created | |
262 * by Gaim 1.5.0 or older this value will be invalid and | |
263 * very small (close to 0). This is because Gaim 1.5.0 | |
264 * and older did not record the timestamp when the status | |
265 * was created. | |
266 * | |
267 * However, this value is guaranteed to be a unique | |
268 * identifier for the given saved status. | |
269 * | |
270 * @param saved_status The saved status. | |
271 * | |
272 * @return The timestamp when this saved status was created. | |
273 */ | |
274 time_t gaim_savedstatus_get_creation_time(const GaimSavedStatus *saved_status); | |
275 | |
276 /** | |
11651 | 277 * Determine if a given saved status has "substatuses," |
278 * or if it is a simple status (the same for all | |
279 * accounts). | |
280 * | |
281 * @param saved_status The saved status. | |
282 * | |
283 * @return TRUE if the saved_status has substatuses. | |
284 * FALSE otherwise. | |
285 */ | |
286 gboolean gaim_savedstatus_has_substatuses(const GaimSavedStatus *saved_status); | |
287 | |
288 /** | |
12056 | 289 * Get the substatus for an account in a saved status. |
290 * | |
12245 | 291 * @param saved_status The saved status. |
292 * @param account The account. | |
12056 | 293 * |
294 * @return The GaimSavedStatusSub for the account, or NULL if | |
295 * the given account does not have a substatus that | |
296 * differs from the default status of this GaimSavedStatus. | |
297 */ | |
12080 | 298 GaimSavedStatusSub *gaim_savedstatus_get_substatus( |
12056 | 299 const GaimSavedStatus *saved_status, |
300 const GaimAccount *account); | |
301 | |
302 /** | |
303 * Get the status type of a given substatus. | |
304 * | |
305 * @param substatus The substatus. | |
306 * | |
307 * @return The status type. | |
308 */ | |
309 const GaimStatusType *gaim_savedstatus_substatus_get_type(const GaimSavedStatusSub *substatus); | |
310 | |
311 /** | |
312 * Get the message of a given substatus. | |
313 * | |
314 * @param substatus The substatus. | |
315 * | |
316 * @return The message of the substatus, or NULL if this substatus does | |
317 * not have a message. | |
318 */ | |
319 const char *gaim_savedstatus_substatus_get_message(const GaimSavedStatusSub *substatus); | |
320 | |
321 /** | |
11724 | 322 * Sets the statuses for all your accounts to those specified |
323 * by the given saved_status. This function calls | |
324 * gaim_savedstatus_activate_for_account() for all your accounts. | |
325 * | |
326 * @param saved_status The status you want to set your accounts to. | |
327 */ | |
12125 | 328 void gaim_savedstatus_activate(GaimSavedStatus *saved_status); |
11724 | 329 |
330 /** | |
331 * Sets the statuses for a given account to those specified | |
332 * by the given saved_status. | |
333 * | |
334 * @param saved_status The status you want to set your accounts to. | |
335 * @param account The account whose statuses you want to change. | |
336 */ | |
337 void gaim_savedstatus_activate_for_account(const GaimSavedStatus *saved_status, GaimAccount *account); | |
338 | |
339 /** | |
10418 | 340 * Get the handle for the status subsystem. |
341 * | |
342 * @return the handle to the status subsystem | |
343 */ | |
12323
fc464a0abccc
[gaim-migrate @ 14627]
Richard Laager <rlaager@wiktel.com>
parents:
12245
diff
changeset
|
344 void *gaim_savedstatuses_get_handle(void); |
10418 | 345 |
346 /** | |
347 * Initializes the status subsystem. | |
348 */ | |
349 void gaim_savedstatuses_init(void); | |
350 | |
351 /** | |
352 * Uninitializes the status subsystem. | |
353 */ | |
354 void gaim_savedstatuses_uninit(void); | |
355 | |
356 /*@}*/ | |
357 | |
358 #endif /* _GAIM_SAVEDSTATUSES_H_ */ |