Mercurial > pidgin.yaz
annotate src/notify.h @ 10868:4a56b48dbaa6
[gaim-migrate @ 12555]
Don't try to send if charset conversion isn't successful. This is entirely untested.
committer: Tailor Script <tailor@pidgin.im>
author | Daniel Atallah <daniel.atallah@gmail.com> |
---|---|
date | Mon, 25 Apr 2005 03:41:16 +0000 |
parents | 62fc579810f4 |
children | 9480e0d0f563 |
rev | line source |
---|---|
5437 | 1 /** |
2 * @file notify.h Notification API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
8046 | 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. | |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
10 * |
5437 | 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_NOTIFY_H_ | |
26 #define _GAIM_NOTIFY_H_ | |
27 | |
28 #include <stdlib.h> | |
29 #include <glib-object.h> | |
30 #include <glib.h> | |
31 | |
9797 | 32 #include "connection.h" |
33 | |
5437 | 34 /** |
35 * Notification types. | |
36 */ | |
37 typedef enum | |
38 { | |
10439 | 39 GAIM_NOTIFY_MESSAGE = 0, /**< Message notification. */ |
40 GAIM_NOTIFY_EMAIL, /**< Single e-mail notification. */ | |
41 GAIM_NOTIFY_EMAILS, /**< Multiple e-mail notification. */ | |
42 GAIM_NOTIFY_FORMATTED, /**< Formatted text. */ | |
43 GAIM_NOTIFY_SEARCHRESULTS, /**< Buddy search results. */ | |
44 GAIM_NOTIFY_USERINFO, /**< Formatted userinfo text. */ | |
45 GAIM_NOTIFY_URI /**< URI notification or display. */ | |
5437 | 46 |
47 } GaimNotifyType; | |
48 | |
49 /** | |
50 * Notification message types. | |
51 */ | |
52 typedef enum | |
53 { | |
54 GAIM_NOTIFY_MSG_ERROR = 0, /**< Error notification. */ | |
55 GAIM_NOTIFY_MSG_WARNING, /**< Warning notification. */ | |
56 GAIM_NOTIFY_MSG_INFO /**< Information notification. */ | |
57 | |
58 } GaimNotifyMsgType; | |
59 | |
60 /** | |
61 * Notification UI operations. | |
62 */ | |
63 typedef struct | |
64 { | |
65 void *(*notify_message)(GaimNotifyMsgType type, const char *title, | |
66 const char *primary, const char *secondary, | |
67 GCallback cb, void *user_data); | |
68 void *(*notify_email)(const char *subject, const char *from, | |
69 const char *to, const char *url, | |
70 GCallback cb, void *user_data); | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
71 void *(*notify_emails)(size_t count, gboolean detailed, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
72 const char **subjects, const char **froms, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
73 const char **tos, const char **urls, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
74 GCallback cb, void *user_data); |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
75 void *(*notify_formatted)(const char *title, const char *primary, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
76 const char *secondary, const char *text, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
77 GCallback cb, void *user_data); |
10439 | 78 void *(*notify_searchresults)(GaimConnection *gc, const char *title, |
79 const char *primary, const char *secondary, | |
80 const char **results, GCallback cb, | |
81 void *user_data); | |
9797 | 82 void *(*notify_userinfo)(GaimConnection *gc, const char *who, |
83 const char *title, const char *primary, | |
84 const char *secondary, const char *text, | |
85 GCallback cb, void *user_data); | |
10240
95ca0db2d01d
[gaim-migrate @ 11377]
Herman Bloggs <hermanator12002@yahoo.com>
parents:
10209
diff
changeset
|
86 void *(*notify_uri)(const char *uri); |
5437 | 87 |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
88 void (*close_notify)(GaimNotifyType type, void *ui_handle); |
5437 | 89 |
90 } GaimNotifyUiOps; | |
91 | |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
92 |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
93 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
94 extern "C" { |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
95 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
96 |
5437 | 97 /**************************************************************************/ |
98 /** @name Notification API */ | |
99 /**************************************************************************/ | |
100 /*@{*/ | |
101 | |
102 /** | |
103 * Displays a notification message to the user. | |
104 * | |
105 * @param handle The plugin or connection handle. | |
106 * @param type The notification type. | |
107 * @param title The title of the message. | |
108 * @param primary The main point of the message. | |
109 * @param secondary The secondary information. | |
110 * @param cb The callback to call when the user closes | |
111 * the notification. | |
112 * @param user_data The data to pass to the callback. | |
113 * | |
114 * @return A UI-specific handle. | |
115 */ | |
6356
ee0044f3e377
[gaim-migrate @ 6855]
Christian Hammond <chipx86@chipx86.com>
parents:
5944
diff
changeset
|
116 void *gaim_notify_message(void *handle, GaimNotifyMsgType type, |
5437 | 117 const char *title, const char *primary, |
118 const char *secondary, GCallback cb, | |
119 void *user_data); | |
120 | |
121 /** | |
122 * Displays a single e-mail notification to the user. | |
123 * | |
124 * @param handle The plugin or connection handle. | |
125 * @param subject The subject of the e-mail. | |
126 * @param from The from address. | |
127 * @param to The destination address. | |
128 * @param url The URL where the message can be read. | |
129 * @param cb The callback to call when the user closes | |
130 * the notification. | |
131 * @param user_data The data to pass to the callback. | |
132 * | |
133 * @return A UI-specific handle. | |
134 */ | |
135 void *gaim_notify_email(void *handle, const char *subject, | |
136 const char *from, const char *to, | |
137 const char *url, GCallback cb, | |
138 void *user_data); | |
139 | |
140 /** | |
141 * Displays a notification for multiple e-mails to the user. | |
142 * | |
143 * @param handle The plugin or connection handle. | |
144 * @param count The number of e-mails. | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
145 * @param detailed @c TRUE if there is information for each e-mail in the |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
146 * arrays. |
5437 | 147 * @param subjects The array of subjects. |
148 * @param froms The array of from addresses. | |
149 * @param tos The array of destination addresses. | |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
150 * @param urls The URLs where the messages can be read. |
5437 | 151 * @param cb The callback to call when the user closes |
152 * the notification. | |
153 * @param user_data The data to pass to the callback. | |
154 * | |
155 * @return A UI-specific handle. | |
156 */ | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
157 void *gaim_notify_emails(void *handle, size_t count, gboolean detailed, |
5437 | 158 const char **subjects, const char **froms, |
159 const char **tos, const char **urls, | |
160 GCallback cb, void *user_data); | |
161 | |
162 /** | |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
163 * Displays a notification with formatted text. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
164 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
165 * The text is essentially a stripped-down format of HTML, the same that |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
166 * IMs may send. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
167 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
168 * @param handle The plugin or connection handle. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
169 * @param title The title of the message. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
170 * @param primary The main point of the message. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
171 * @param secondary The secondary information. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
172 * @param text The formatted text. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
173 * @param cb The callback to call when the user closes |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
174 * the notification. |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
175 * @param user_data The data to pass to the callback. |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
176 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
177 * @return A UI-specific handle. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
178 */ |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
179 void *gaim_notify_formatted(void *handle, const char *title, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
180 const char *primary, const char *secondary, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
181 const char *text, GCallback cb, void *user_data); |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
182 |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
183 /** |
10439 | 184 * Displays results from a buddy search. This can be, for example, |
185 * a window with a list of all found buddies, where you are given the | |
186 * option of adding buddies to your buddy list. | |
187 * | |
188 * @param gc The GaimConnection handle associated with the information. | |
189 * @param title The title of the message. If this is NULL, the title | |
190 * will be "Search Results." | |
191 * @param primary The main point of the message. | |
192 * @param secondary The secondary information. | |
10443 | 193 * @param results An null-terminated array of null-terminated buddy names. |
10439 | 194 * @param cb The callback to call when the user closes |
195 * the notification. | |
196 * @param user_data The data to pass to the callback. | |
197 * | |
198 * @return A UI-specific handle. | |
199 */ | |
200 void *gaim_notify_searchresults(GaimConnection *gc, const char *title, | |
201 const char *primary, const char *secondary, | |
202 const char **results, GCallback cb, | |
203 void *user_data); | |
204 | |
205 /** | |
9800 | 206 * Displays user information with formatted text, passing information giving |
207 * the connection and username from which the user information came. | |
9797 | 208 * |
209 * The text is essentially a stripped-down format of HTML, the same that | |
210 * IMs may send. | |
211 * | |
212 * @param gc The GaimConnection handle associated with the information. | |
213 * @param who The username associated with the information. | |
214 * @param title The title of the message. | |
215 * @param primary The main point of the message. | |
216 * @param secondary The secondary information. | |
217 * @param text The formatted text. | |
218 * @param cb The callback to call when the user closes | |
219 * the notification. | |
220 * @param user_data The data to pass to the callback. | |
221 * | |
222 * @return A UI-specific handle. | |
223 */ | |
224 void *gaim_notify_userinfo(GaimConnection *gc, const char *who, | |
225 const char *title, const char *primary, | |
226 const char *secondary, const char *text, | |
227 GCallback cb, void *user_data); | |
228 | |
229 /** | |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
230 * Opens a URI or somehow presents it to the user. |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
231 * |
10240
95ca0db2d01d
[gaim-migrate @ 11377]
Herman Bloggs <hermanator12002@yahoo.com>
parents:
10209
diff
changeset
|
232 * @param handle The plugin or connection handle. |
95ca0db2d01d
[gaim-migrate @ 11377]
Herman Bloggs <hermanator12002@yahoo.com>
parents:
10209
diff
changeset
|
233 * @param uri The URI to display or go to. |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
234 * |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
235 * @return A UI-specific handle, if any. This may only be presented if |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
236 * the UI code displays a dialog instead of a webpage, or something |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
237 * similar. |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
238 */ |
10240
95ca0db2d01d
[gaim-migrate @ 11377]
Herman Bloggs <hermanator12002@yahoo.com>
parents:
10209
diff
changeset
|
239 void *gaim_notify_uri(void *handle, const char *uri); |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
240 |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
241 /** |
5437 | 242 * Closes a notification. |
243 * | |
244 * This should be used only by the UI operation functions and part of the | |
245 * core. | |
246 * | |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
247 * @param type The notification type. |
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
248 * @param ui_handle The notification UI handle. |
5437 | 249 */ |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
250 void gaim_notify_close(GaimNotifyType type, void *ui_handle); |
5437 | 251 |
252 /** | |
253 * Closes all notifications registered with the specified handle. | |
254 * | |
255 * @param handle The handle. | |
256 */ | |
257 void gaim_notify_close_with_handle(void *handle); | |
258 | |
259 /** | |
260 * A wrapper for gaim_notify_message that displays an information message. | |
261 */ | |
262 #define gaim_notify_info(handle, title, primary, secondary) \ | |
263 gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \ | |
264 (primary), (secondary), NULL, NULL) | |
265 | |
266 /** | |
267 * A wrapper for gaim_notify_message that displays a warning message. | |
268 */ | |
269 #define gaim_notify_warning(handle, title, primary, secondary) \ | |
270 gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \ | |
271 (primary), (secondary), NULL, NULL) | |
272 | |
273 /** | |
274 * A wrapper for gaim_notify_message that displays an error message. | |
275 */ | |
276 #define gaim_notify_error(handle, title, primary, secondary) \ | |
277 gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \ | |
278 (primary), (secondary), NULL, NULL) | |
279 | |
280 /*@}*/ | |
281 | |
282 /**************************************************************************/ | |
10566
62fc579810f4
[gaim-migrate @ 11949]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10443
diff
changeset
|
283 /** @name UI Registration Functions */ |
5437 | 284 /**************************************************************************/ |
285 /*@{*/ | |
286 | |
287 /** | |
288 * Sets the UI operations structure to be used when displaying a | |
289 * notification. | |
290 * | |
291 * @param ops The UI operations structure. | |
292 */ | |
7035
feb3d21a7794
[gaim-migrate @ 7598]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
293 void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops); |
5437 | 294 |
295 /** | |
296 * Returns the UI operations structure to be used when displaying a | |
297 * notification. | |
298 * | |
6467
aabb0b331ac8
[gaim-migrate @ 6976]
Christian Hammond <chipx86@chipx86.com>
parents:
6465
diff
changeset
|
299 * @return The UI operations structure. |
5437 | 300 */ |
7035
feb3d21a7794
[gaim-migrate @ 7598]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
301 GaimNotifyUiOps *gaim_notify_get_ui_ops(void); |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
302 |
5497 | 303 /*@}*/ |
5437 | 304 |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
305 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
306 } |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
307 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
308 |
5437 | 309 #endif /* _GAIM_NOTIFY_H_ */ |