Mercurial > pidgin
annotate src/notify.h @ 10188:5709800d1dee
[gaim-migrate @ 11303]
I really like this a lot better... hope I'm not stepping on any toes...
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Mon, 15 Nov 2004 03:53:56 +0000 |
parents | cc68a8c6e741 |
children | 9e0b98c458b1 |
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 { | |
39 GAIM_NOTIFY_MESSAGE = 0, /**< Message notification. */ | |
40 GAIM_NOTIFY_EMAIL, /**< Single e-mail notification. */ | |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
41 GAIM_NOTIFY_EMAILS, /**< Multiple e-mail notification. */ |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
42 GAIM_NOTIFY_FORMATTED, /**< Formatted text. */ |
9797 | 43 GAIM_NOTIFY_USERINFO, /**< Formatted userinfo text. */ |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
44 GAIM_NOTIFY_URI /**< URI notification or display. */ |
5437 | 45 |
46 } GaimNotifyType; | |
47 | |
48 /** | |
49 * Notification message types. | |
50 */ | |
51 typedef enum | |
52 { | |
53 GAIM_NOTIFY_MSG_ERROR = 0, /**< Error notification. */ | |
54 GAIM_NOTIFY_MSG_WARNING, /**< Warning notification. */ | |
55 GAIM_NOTIFY_MSG_INFO /**< Information notification. */ | |
56 | |
57 } GaimNotifyMsgType; | |
58 | |
59 /** | |
60 * Notification UI operations. | |
61 */ | |
62 typedef struct | |
63 { | |
64 void *(*notify_message)(GaimNotifyMsgType type, const char *title, | |
65 const char *primary, const char *secondary, | |
66 GCallback cb, void *user_data); | |
67 void *(*notify_email)(const char *subject, const char *from, | |
68 const char *to, const char *url, | |
69 GCallback cb, void *user_data); | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
70 void *(*notify_emails)(size_t count, gboolean detailed, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
71 const char **subjects, const char **froms, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
72 const char **tos, const char **urls, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
73 GCallback cb, void *user_data); |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
74 void *(*notify_formatted)(const char *title, const char *primary, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
75 const char *secondary, const char *text, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
76 GCallback cb, void *user_data); |
9797 | 77 void *(*notify_userinfo)(GaimConnection *gc, const char *who, |
78 const char *title, const char *primary, | |
79 const char *secondary, const char *text, | |
80 GCallback cb, void *user_data); | |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
81 void *(*notify_uri)(const char *uri); |
5437 | 82 |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
83 void (*close_notify)(GaimNotifyType type, void *ui_handle); |
5437 | 84 |
85 } GaimNotifyUiOps; | |
86 | |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
87 |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
88 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
89 extern "C" { |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
90 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
91 |
5437 | 92 /**************************************************************************/ |
93 /** @name Notification API */ | |
94 /**************************************************************************/ | |
95 /*@{*/ | |
96 | |
97 /** | |
98 * Displays a notification message to the user. | |
99 * | |
100 * @param handle The plugin or connection handle. | |
101 * @param type The notification type. | |
102 * @param title The title of the message. | |
103 * @param primary The main point of the message. | |
104 * @param secondary The secondary information. | |
105 * @param cb The callback to call when the user closes | |
106 * the notification. | |
107 * @param user_data The data to pass to the callback. | |
108 * | |
109 * @return A UI-specific handle. | |
110 */ | |
6356
ee0044f3e377
[gaim-migrate @ 6855]
Christian Hammond <chipx86@chipx86.com>
parents:
5944
diff
changeset
|
111 void *gaim_notify_message(void *handle, GaimNotifyMsgType type, |
5437 | 112 const char *title, const char *primary, |
113 const char *secondary, GCallback cb, | |
114 void *user_data); | |
115 | |
116 /** | |
117 * Displays a single e-mail notification to the user. | |
118 * | |
119 * @param handle The plugin or connection handle. | |
120 * @param subject The subject of the e-mail. | |
121 * @param from The from address. | |
122 * @param to The destination address. | |
123 * @param url The URL where the message can be read. | |
124 * @param cb The callback to call when the user closes | |
125 * the notification. | |
126 * @param user_data The data to pass to the callback. | |
127 * | |
128 * @return A UI-specific handle. | |
129 */ | |
130 void *gaim_notify_email(void *handle, const char *subject, | |
131 const char *from, const char *to, | |
132 const char *url, GCallback cb, | |
133 void *user_data); | |
134 | |
135 /** | |
136 * Displays a notification for multiple e-mails to the user. | |
137 * | |
138 * @param handle The plugin or connection handle. | |
139 * @param count The number of e-mails. | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
140 * @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
|
141 * arrays. |
5437 | 142 * @param subjects The array of subjects. |
143 * @param froms The array of from addresses. | |
144 * @param tos The array of destination addresses. | |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
145 * @param urls The URLs where the messages can be read. |
5437 | 146 * @param cb The callback to call when the user closes |
147 * the notification. | |
148 * @param user_data The data to pass to the callback. | |
149 * | |
150 * @return A UI-specific handle. | |
151 */ | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
152 void *gaim_notify_emails(void *handle, size_t count, gboolean detailed, |
5437 | 153 const char **subjects, const char **froms, |
154 const char **tos, const char **urls, | |
155 GCallback cb, void *user_data); | |
156 | |
157 /** | |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
158 * Displays a notification with formatted text. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
159 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
160 * 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
|
161 * IMs may send. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
162 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
163 * @param handle The plugin or connection handle. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
164 * @param title The title of the message. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
165 * @param primary The main point of the message. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
166 * @param secondary The secondary information. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
167 * @param text The formatted text. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
168 * @param cb The callback to call when the user closes |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
169 * the notification. |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
170 * @param user_data The data to pass to the callback. |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
171 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
172 * @return A UI-specific handle. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
173 */ |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
174 void *gaim_notify_formatted(void *handle, const char *title, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
175 const char *primary, const char *secondary, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
176 const char *text, GCallback cb, void *user_data); |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
177 |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
178 /** |
9800 | 179 * Displays user information with formatted text, passing information giving |
180 * the connection and username from which the user information came. | |
9797 | 181 * |
182 * The text is essentially a stripped-down format of HTML, the same that | |
183 * IMs may send. | |
184 * | |
185 * @param gc The GaimConnection handle associated with the information. | |
186 * @param who The username associated with the information. | |
187 * @param title The title of the message. | |
188 * @param primary The main point of the message. | |
189 * @param secondary The secondary information. | |
190 * @param text The formatted text. | |
191 * @param cb The callback to call when the user closes | |
192 * the notification. | |
193 * @param user_data The data to pass to the callback. | |
194 * | |
195 * @return A UI-specific handle. | |
196 */ | |
197 void *gaim_notify_userinfo(GaimConnection *gc, const char *who, | |
198 const char *title, const char *primary, | |
199 const char *secondary, const char *text, | |
200 GCallback cb, void *user_data); | |
201 | |
202 /** | |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
203 * Opens a URI or somehow presents it to the user. |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
204 * |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
205 * @param handle The plugin or connection handle. |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
206 * @param uri The URI to display or go to. |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
207 * |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
208 * @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
|
209 * 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
|
210 * similar. |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
211 */ |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
212 void *gaim_notify_uri(void *handle, const char *uri); |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
213 |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
214 /** |
5437 | 215 * Closes a notification. |
216 * | |
217 * This should be used only by the UI operation functions and part of the | |
218 * core. | |
219 * | |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
220 * @param type The notification type. |
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
221 * @param ui_handle The notification UI handle. |
5437 | 222 */ |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
223 void gaim_notify_close(GaimNotifyType type, void *ui_handle); |
5437 | 224 |
225 /** | |
226 * Closes all notifications registered with the specified handle. | |
227 * | |
228 * @param handle The handle. | |
229 */ | |
230 void gaim_notify_close_with_handle(void *handle); | |
231 | |
232 /** | |
233 * A wrapper for gaim_notify_message that displays an information message. | |
234 */ | |
235 #define gaim_notify_info(handle, title, primary, secondary) \ | |
236 gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \ | |
237 (primary), (secondary), NULL, NULL) | |
238 | |
239 /** | |
240 * A wrapper for gaim_notify_message that displays a warning message. | |
241 */ | |
242 #define gaim_notify_warning(handle, title, primary, secondary) \ | |
243 gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \ | |
244 (primary), (secondary), NULL, NULL) | |
245 | |
246 /** | |
247 * A wrapper for gaim_notify_message that displays an error message. | |
248 */ | |
249 #define gaim_notify_error(handle, title, primary, secondary) \ | |
250 gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \ | |
251 (primary), (secondary), NULL, NULL) | |
252 | |
253 /*@}*/ | |
254 | |
255 /**************************************************************************/ | |
256 /** @name UI Operations API */ | |
257 /**************************************************************************/ | |
258 /*@{*/ | |
259 | |
260 /** | |
261 * Sets the UI operations structure to be used when displaying a | |
262 * notification. | |
263 * | |
264 * @param ops The UI operations structure. | |
265 */ | |
7035
feb3d21a7794
[gaim-migrate @ 7598]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
266 void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops); |
5437 | 267 |
268 /** | |
269 * Returns the UI operations structure to be used when displaying a | |
270 * notification. | |
271 * | |
6467
aabb0b331ac8
[gaim-migrate @ 6976]
Christian Hammond <chipx86@chipx86.com>
parents:
6465
diff
changeset
|
272 * @return The UI operations structure. |
5437 | 273 */ |
7035
feb3d21a7794
[gaim-migrate @ 7598]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
274 GaimNotifyUiOps *gaim_notify_get_ui_ops(void); |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
275 |
5497 | 276 /*@}*/ |
5437 | 277 |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
278 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
279 } |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
280 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
281 |
5437 | 282 #endif /* _GAIM_NOTIFY_H_ */ |