Mercurial > pidgin
annotate src/notify.h @ 7172:895cd1d03efb
[gaim-migrate @ 7740]
I added buddy comment support for AIM and ICQ
I also fixed a tini memleak in gaim_request_something when
using a multiline dialog.
I also tried to organize ChangeLog some. I put stuff that
I thought normal people would care about the most at the top,
and tried to group stuff aimed at plugin authors together, and
nearer to the bottom. Feel free to do a better job than me.
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Mon, 06 Oct 2003 03:21:33 +0000 |
parents | feb3d21a7794 |
children | fa6395637e2c |
rev | line source |
---|---|
5437 | 1 /** |
2 * @file notify.h Notification API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Copyright (C) 2003 Christian Hammond <chipx86@gnupdate.org> | |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
8 * |
5437 | 9 * This program is free software; you can redistribute it and/or modify |
10 * it under the terms of the GNU General Public License as published by | |
11 * the Free Software Foundation; either version 2 of the License, or | |
12 * (at your option) any later version. | |
13 * | |
14 * This program is distributed in the hope that it will be useful, | |
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 * GNU General Public License for more details. | |
18 * | |
19 * You should have received a copy of the GNU General Public License | |
20 * along with this program; if not, write to the Free Software | |
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
22 */ | |
23 #ifndef _GAIM_NOTIFY_H_ | |
24 #define _GAIM_NOTIFY_H_ | |
25 | |
26 #include <stdlib.h> | |
27 #include <glib-object.h> | |
28 #include <glib.h> | |
29 | |
30 /** | |
31 * Notification types. | |
32 */ | |
33 typedef enum | |
34 { | |
35 GAIM_NOTIFY_MESSAGE = 0, /**< Message notification. */ | |
36 GAIM_NOTIFY_EMAIL, /**< Single e-mail notification. */ | |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
37 GAIM_NOTIFY_EMAILS, /**< Multiple e-mail notification. */ |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
38 GAIM_NOTIFY_FORMATTED, /**< Formatted text. */ |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
39 GAIM_NOTIFY_URI /**< URI notification or display. */ |
5437 | 40 |
41 } GaimNotifyType; | |
42 | |
43 /** | |
44 * Notification message types. | |
45 */ | |
46 typedef enum | |
47 { | |
48 GAIM_NOTIFY_MSG_ERROR = 0, /**< Error notification. */ | |
49 GAIM_NOTIFY_MSG_WARNING, /**< Warning notification. */ | |
50 GAIM_NOTIFY_MSG_INFO /**< Information notification. */ | |
51 | |
52 } GaimNotifyMsgType; | |
53 | |
54 /** | |
55 * Notification UI operations. | |
56 */ | |
57 typedef struct | |
58 { | |
59 void *(*notify_message)(GaimNotifyMsgType type, const char *title, | |
60 const char *primary, const char *secondary, | |
61 GCallback cb, void *user_data); | |
62 void *(*notify_email)(const char *subject, const char *from, | |
63 const char *to, const char *url, | |
64 GCallback cb, void *user_data); | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
65 void *(*notify_emails)(size_t count, gboolean detailed, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
66 const char **subjects, const char **froms, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
67 const char **tos, const char **urls, |
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
68 GCallback cb, void *user_data); |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
69 void *(*notify_formatted)(const char *title, const char *primary, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
70 const char *secondary, const char *text, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
71 GCallback cb, void *user_data); |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
72 void *(*notify_uri)(const char *uri); |
5437 | 73 |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
74 void (*close_notify)(GaimNotifyType type, void *ui_handle); |
5437 | 75 |
76 } GaimNotifyUiOps; | |
77 | |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
78 |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
79 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
80 extern "C" { |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
81 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
82 |
5437 | 83 /**************************************************************************/ |
84 /** @name Notification API */ | |
85 /**************************************************************************/ | |
86 /*@{*/ | |
87 | |
88 /** | |
89 * Displays a notification message to the user. | |
90 * | |
91 * @param handle The plugin or connection handle. | |
92 * @param type The notification type. | |
93 * @param title The title of the message. | |
94 * @param primary The main point of the message. | |
95 * @param secondary The secondary information. | |
96 * @param cb The callback to call when the user closes | |
97 * the notification. | |
98 * @param user_data The data to pass to the callback. | |
99 * | |
100 * @return A UI-specific handle. | |
101 */ | |
6356
ee0044f3e377
[gaim-migrate @ 6855]
Christian Hammond <chipx86@chipx86.com>
parents:
5944
diff
changeset
|
102 void *gaim_notify_message(void *handle, GaimNotifyMsgType type, |
5437 | 103 const char *title, const char *primary, |
104 const char *secondary, GCallback cb, | |
105 void *user_data); | |
106 | |
107 /** | |
108 * Displays a single e-mail notification to the user. | |
109 * | |
110 * @param handle The plugin or connection handle. | |
111 * @param subject The subject of the e-mail. | |
112 * @param from The from address. | |
113 * @param to The destination address. | |
114 * @param url The URL where the message can be read. | |
115 * @param cb The callback to call when the user closes | |
116 * the notification. | |
117 * @param user_data The data to pass to the callback. | |
118 * | |
119 * @return A UI-specific handle. | |
120 */ | |
121 void *gaim_notify_email(void *handle, const char *subject, | |
122 const char *from, const char *to, | |
123 const char *url, GCallback cb, | |
124 void *user_data); | |
125 | |
126 /** | |
127 * Displays a notification for multiple e-mails to the user. | |
128 * | |
129 * @param handle The plugin or connection handle. | |
130 * @param count The number of e-mails. | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
131 * @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
|
132 * arrays. |
5437 | 133 * @param subjects The array of subjects. |
134 * @param froms The array of from addresses. | |
135 * @param tos The array of destination addresses. | |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
136 * @param urls The URLs where the messages can be read. |
5437 | 137 * @param cb The callback to call when the user closes |
138 * the notification. | |
139 * @param user_data The data to pass to the callback. | |
140 * | |
141 * @return A UI-specific handle. | |
142 */ | |
5522
a3e6a5ef49b5
[gaim-migrate @ 5922]
Christian Hammond <chipx86@chipx86.com>
parents:
5497
diff
changeset
|
143 void *gaim_notify_emails(void *handle, size_t count, gboolean detailed, |
5437 | 144 const char **subjects, const char **froms, |
145 const char **tos, const char **urls, | |
146 GCallback cb, void *user_data); | |
147 | |
148 /** | |
6381
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
149 * Displays a notification with formatted text. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
150 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
151 * 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
|
152 * IMs may send. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
153 * |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
154 * @param handle The plugin or connection handle. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
155 * @param title The title of the message. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
156 * @param primary The main point of the message. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
157 * @param secondary The secondary information. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
158 * @param text The formatted text. |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
159 * @param cb The callback to call when the user closes |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
160 * the notification. |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
161 * @param user_data The data to pass to the callback. |
6381
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 * @return A UI-specific handle. |
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 void *gaim_notify_formatted(void *handle, const char *title, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
166 const char *primary, const char *secondary, |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
167 const char *text, GCallback cb, void *user_data); |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
168 |
e006685f75aa
[gaim-migrate @ 6886]
Christian Hammond <chipx86@chipx86.com>
parents:
6356
diff
changeset
|
169 /** |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
170 * Opens a URI or somehow presents it to the user. |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
171 * |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
172 * @param handle The plugin or connection handle. |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6467
diff
changeset
|
173 * @param uri The URI to display or go to. |
6465
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
174 * |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
175 * @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
|
176 * 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
|
177 * similar. |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
178 */ |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
179 void *gaim_notify_uri(void *handle, const char *uri); |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
180 |
fb64cc87bc96
[gaim-migrate @ 6974]
Christian Hammond <chipx86@chipx86.com>
parents:
6381
diff
changeset
|
181 /** |
5437 | 182 * Closes a notification. |
183 * | |
184 * This should be used only by the UI operation functions and part of the | |
185 * core. | |
186 * | |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
187 * @param type The notification type. |
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
188 * @param ui_handle The notification UI handle. |
5437 | 189 */ |
5476
9bcd8cd625ae
[gaim-migrate @ 5872]
Christian Hammond <chipx86@chipx86.com>
parents:
5437
diff
changeset
|
190 void gaim_notify_close(GaimNotifyType type, void *ui_handle); |
5437 | 191 |
192 /** | |
193 * Closes all notifications registered with the specified handle. | |
194 * | |
195 * @param handle The handle. | |
196 */ | |
197 void gaim_notify_close_with_handle(void *handle); | |
198 | |
199 /** | |
200 * A wrapper for gaim_notify_message that displays an information message. | |
201 */ | |
202 #define gaim_notify_info(handle, title, primary, secondary) \ | |
203 gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \ | |
204 (primary), (secondary), NULL, NULL) | |
205 | |
206 /** | |
207 * A wrapper for gaim_notify_message that displays a warning message. | |
208 */ | |
209 #define gaim_notify_warning(handle, title, primary, secondary) \ | |
210 gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \ | |
211 (primary), (secondary), NULL, NULL) | |
212 | |
213 /** | |
214 * A wrapper for gaim_notify_message that displays an error message. | |
215 */ | |
216 #define gaim_notify_error(handle, title, primary, secondary) \ | |
217 gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \ | |
218 (primary), (secondary), NULL, NULL) | |
219 | |
220 /*@}*/ | |
221 | |
222 /**************************************************************************/ | |
223 /** @name UI Operations API */ | |
224 /**************************************************************************/ | |
225 /*@{*/ | |
226 | |
227 /** | |
228 * Sets the UI operations structure to be used when displaying a | |
229 * notification. | |
230 * | |
231 * @param ops The UI operations structure. | |
232 */ | |
7035
feb3d21a7794
[gaim-migrate @ 7598]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
233 void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops); |
5437 | 234 |
235 /** | |
236 * Returns the UI operations structure to be used when displaying a | |
237 * notification. | |
238 * | |
6467
aabb0b331ac8
[gaim-migrate @ 6976]
Christian Hammond <chipx86@chipx86.com>
parents:
6465
diff
changeset
|
239 * @return The UI operations structure. |
5437 | 240 */ |
7035
feb3d21a7794
[gaim-migrate @ 7598]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
241 GaimNotifyUiOps *gaim_notify_get_ui_ops(void); |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
242 |
5497 | 243 /*@}*/ |
5437 | 244 |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
245 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
246 } |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
247 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5522
diff
changeset
|
248 |
5437 | 249 #endif /* _GAIM_NOTIFY_H_ */ |