Mercurial > pidgin.yaz
annotate libgaim/prpl.h @ 15144:b81e4e44b509
[gaim-migrate @ 17929]
User Info and Tooltips now use the GaimNotifyUserInfo object and methods defined in notify.h. GaimNotifyUserInfo objects encapsulate a list of GaimNotifyUserInfoEntry objects, each of which may have a label, a value, and be specified to be a section header.
This moves the burden of UI generation of user information from the various prpls to the UI. The UI can choose how to display the information rather than being fenced into a particular HTML formatting. Consistency across the prpls' information presentation is now enforced, as well. gaim_notify_user_info_get_text_with_newline() generates text in the:
<b>label</b>: value
<b>label</b>: value
format as was passed by convention from prpls in the past.
committer: Tailor Script <tailor@pidgin.im>
author | Evan Schoenberg <evan.s@dreskin.net> |
---|---|
date | Sun, 10 Dec 2006 02:53:09 +0000 |
parents | c8957b9c6202 |
children | 4bf7801a2539 |
rev | line source |
---|---|
14192 | 1 /** |
2 * @file prpl.h Protocol Plugin functions | |
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 | |
26 /* this file should be all that prpls need to include. therefore, by including | |
27 * this file, they should get glib, proxy, gaim_connection, prpl, etc. */ | |
28 | |
29 #ifndef _GAIM_PRPL_H_ | |
30 #define _GAIM_PRPL_H_ | |
31 | |
32 typedef struct _GaimPluginProtocolInfo GaimPluginProtocolInfo; | |
33 | |
34 /**************************************************************************/ | |
35 /** @name Basic Protocol Information */ | |
36 /**************************************************************************/ | |
37 | |
38 typedef enum { | |
39 GAIM_ICON_SCALE_DISPLAY = 0x01, /**< We scale the icon when we display it */ | |
40 GAIM_ICON_SCALE_SEND = 0x02 /**< We scale the icon before we send it to the server */ | |
41 } GaimIconScaleRules; | |
42 | |
43 | |
44 /** | |
45 * A description of a Buddy Icon specification. This tells Gaim what kind of image file | |
46 * it should give this prpl, and what kind of image file it should expect back. | |
47 * Dimensions less than 1 should be ignored and the image not scaled. | |
48 */ | |
49 typedef struct { | |
50 char *format; /**< This is a comma-delimited list of image formats or NULL if icons are not supported. | |
14941
28c7e23bcc7e
[gaim-migrate @ 17712]
Richard Laager <rlaager@wiktel.com>
parents:
14542
diff
changeset
|
51 * Neither the core nor the prpl will actually check to see if the data it's given matches this; it's |
28c7e23bcc7e
[gaim-migrate @ 17712]
Richard Laager <rlaager@wiktel.com>
parents:
14542
diff
changeset
|
52 * entirely up to the UI to do what it wants */ |
14192 | 53 int min_width; /**< The minimum width of this icon */ |
54 int min_height; /**< The minimum height of this icon */ | |
55 int max_width; /**< The maximum width of this icon */ | |
56 int max_height; /**< The maximum height of this icon */ | |
57 GaimIconScaleRules scale_rules; /**< How to stretch this icon */ | |
58 } GaimBuddyIconSpec; | |
59 | |
60 /** | |
61 * This \#define exists just to make it easier to fill out the buddy icon | |
62 * field in the prpl info struct for protocols that couldn't care less. | |
63 */ | |
64 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0} | |
65 | |
66 #include "blist.h" | |
67 #include "conversation.h" | |
68 #include "ft.h" | |
15144
b81e4e44b509
[gaim-migrate @ 17929]
Evan Schoenberg <evan.s@dreskin.net>
parents:
15124
diff
changeset
|
69 #include "notify.h" |
14192 | 70 #include "proxy.h" |
71 #include "plugin.h" | |
72 #include "roomlist.h" | |
73 #include "status.h" | |
74 #include "whiteboard.h" | |
75 | |
76 struct proto_chat_entry { | |
77 const char *label; | |
78 const char *identifier; | |
79 gboolean required; | |
80 gboolean is_int; | |
81 int min; | |
82 int max; | |
83 gboolean secret; | |
84 }; | |
85 | |
86 /** | |
87 * Protocol options | |
88 * | |
89 * These should all be stuff that some plugins can do and others can't. | |
90 */ | |
91 typedef enum | |
92 { | |
93 /** | |
94 * Use a unique name, not an alias, for chat rooms. | |
95 * | |
96 * Jabber lets you choose what name you want for chat. | |
97 * So it shouldn't be pulling the alias for when you're in chat; | |
98 * it gets annoying. | |
99 */ | |
100 OPT_PROTO_UNIQUE_CHATNAME = 0x00000004, | |
101 | |
102 /** | |
103 * Chat rooms have topics. | |
104 * | |
105 * IRC and Jabber support this. | |
106 */ | |
107 OPT_PROTO_CHAT_TOPIC = 0x00000008, | |
108 | |
109 /** | |
110 * Don't require passwords for sign-in. | |
111 * | |
112 * Zephyr doesn't require passwords, so there's no | |
113 * need for a password prompt. | |
114 */ | |
115 OPT_PROTO_NO_PASSWORD = 0x00000010, | |
116 | |
117 /** | |
118 * Notify on new mail. | |
119 * | |
120 * MSN and Yahoo notify you when you have new mail. | |
121 */ | |
122 OPT_PROTO_MAIL_CHECK = 0x00000020, | |
123 | |
124 /** | |
125 * Images in IMs. | |
126 * | |
127 * Oscar lets you send images in direct IMs. | |
128 */ | |
129 OPT_PROTO_IM_IMAGE = 0x00000040, | |
130 | |
131 /** | |
132 * Allow passwords to be optional. | |
133 * | |
134 * Passwords in IRC are optional, and are needed for certain | |
135 * functionality. | |
136 */ | |
137 OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080, | |
138 | |
139 /** | |
140 * Allows font size to be specified in sane point size | |
141 * | |
142 * Probably just Jabber and Y!M | |
143 */ | |
144 OPT_PROTO_USE_POINTSIZE = 0x00000100, | |
145 | |
146 /** | |
147 * Set the Register button active when screenname is not given. | |
148 * | |
149 * Gadu-Gadu doesn't need a screenname to register new account. | |
150 */ | |
151 OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200, | |
152 | |
153 } GaimProtocolOptions; | |
154 | |
155 /** | |
156 * A protocol plugin information structure. | |
157 * | |
158 * Every protocol plugin initializes this structure. It is the gateway | |
159 * between gaim and the protocol plugin. Many of this callbacks can be | |
160 * NULL. If a callback must be implemented, it has a comment indicating so. | |
161 */ | |
162 struct _GaimPluginProtocolInfo | |
163 { | |
164 GaimProtocolOptions options; /**< Protocol options. */ | |
165 | |
166 GList *user_splits; /* A GList of GaimAccountUserSplit */ | |
167 GList *protocol_options; /* A GList of GaimAccountOption */ | |
168 | |
169 GaimBuddyIconSpec icon_spec; /* The icon spec. */ | |
170 | |
171 /** | |
172 * Returns the base icon name for the given buddy and account. | |
173 * If buddy is NULL, it will return the name to use for the account's | |
174 * icon. This must be implemented. | |
175 */ | |
176 const char *(*list_icon)(GaimAccount *account, GaimBuddy *buddy); | |
177 | |
178 /** | |
179 * Fills the four char**'s with string identifiers for "emblems" | |
180 * that the UI will interpret and display as relevant | |
181 */ | |
182 void (*list_emblems)(GaimBuddy *buddy, const char **se, const char **sw, | |
183 const char **nw, const char **ne); | |
184 | |
185 /** | |
186 * Gets a short string representing this buddy's status. This will | |
187 * be shown on the buddy list. | |
188 */ | |
189 char *(*status_text)(GaimBuddy *buddy); | |
190 | |
191 /** | |
192 * Allows the prpl to add text to a buddy's tooltip. | |
193 */ | |
15144
b81e4e44b509
[gaim-migrate @ 17929]
Evan Schoenberg <evan.s@dreskin.net>
parents:
15124
diff
changeset
|
194 void (*tooltip_text)(GaimBuddy *buddy, GaimNotifyUserInfo *user_info, gboolean full); |
14192 | 195 |
196 /** | |
197 * This must be implemented, and must add at least the offline | |
198 * and online states. | |
199 */ | |
200 GList *(*status_types)(GaimAccount *account); | |
201 | |
202 GList *(*blist_node_menu)(GaimBlistNode *node); | |
203 GList *(*chat_info)(GaimConnection *); | |
204 GHashTable *(*chat_info_defaults)(GaimConnection *, const char *chat_name); | |
205 | |
206 /* All the server-related functions */ | |
207 | |
208 /** This must be implemented. */ | |
209 void (*login)(GaimAccount *); | |
210 | |
211 /** This must be implemented. */ | |
212 void (*close)(GaimConnection *); | |
213 | |
214 /** | |
215 * This PRPL function should return a positive value on success. | |
216 * If the message is too big to be sent, return -E2BIG. If | |
217 * the account is not connected, return -ENOTCONN. If the | |
218 * PRPL is unable to send the message for another reason, return | |
219 * some other negative value. You can use one of the valid | |
220 * errno values, or just big something. If the message should | |
221 * not be echoed to the conversation window, return 0. | |
222 */ | |
223 int (*send_im)(GaimConnection *, const char *who, | |
224 const char *message, | |
225 GaimMessageFlags flags); | |
226 | |
227 void (*set_info)(GaimConnection *, const char *info); | |
228 unsigned int (*send_typing)(GaimConnection *, const char *name, GaimTypingState state); | |
229 void (*get_info)(GaimConnection *, const char *who); | |
230 void (*set_status)(GaimAccount *account, GaimStatus *status); | |
231 | |
232 void (*set_idle)(GaimConnection *, int idletime); | |
233 void (*change_passwd)(GaimConnection *, const char *old_pass, | |
234 const char *new_pass); | |
235 void (*add_buddy)(GaimConnection *, GaimBuddy *buddy, GaimGroup *group); | |
236 void (*add_buddies)(GaimConnection *, GList *buddies, GList *groups); | |
237 void (*remove_buddy)(GaimConnection *, GaimBuddy *buddy, GaimGroup *group); | |
238 void (*remove_buddies)(GaimConnection *, GList *buddies, GList *groups); | |
239 void (*add_permit)(GaimConnection *, const char *name); | |
240 void (*add_deny)(GaimConnection *, const char *name); | |
241 void (*rem_permit)(GaimConnection *, const char *name); | |
242 void (*rem_deny)(GaimConnection *, const char *name); | |
243 void (*set_permit_deny)(GaimConnection *); | |
244 void (*join_chat)(GaimConnection *, GHashTable *components); | |
245 void (*reject_chat)(GaimConnection *, GHashTable *components); | |
246 char *(*get_chat_name)(GHashTable *components); | |
247 void (*chat_invite)(GaimConnection *, int id, | |
14975
c0d6f960675b
[gaim-migrate @ 17753]
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
14941
diff
changeset
|
248 const char *message, const char *who); |
14192 | 249 void (*chat_leave)(GaimConnection *, int id); |
250 void (*chat_whisper)(GaimConnection *, int id, | |
251 const char *who, const char *message); | |
252 int (*chat_send)(GaimConnection *, int id, const char *message, GaimMessageFlags flags); | |
253 void (*keepalive)(GaimConnection *); | |
254 | |
255 /* new user registration */ | |
256 void (*register_user)(GaimAccount *); | |
257 | |
258 /* get "chat buddy" info and away message */ | |
259 void (*get_cb_info)(GaimConnection *, int, const char *who); | |
260 void (*get_cb_away)(GaimConnection *, int, const char *who); | |
261 | |
262 /* save/store buddy's alias on server list/roster */ | |
263 void (*alias_buddy)(GaimConnection *, const char *who, | |
264 const char *alias); | |
265 | |
266 /* change a buddy's group on a server list/roster */ | |
267 void (*group_buddy)(GaimConnection *, const char *who, | |
268 const char *old_group, const char *new_group); | |
269 | |
270 /* rename a group on a server list/roster */ | |
271 void (*rename_group)(GaimConnection *, const char *old_name, | |
272 GaimGroup *group, GList *moved_buddies); | |
273 | |
274 void (*buddy_free)(GaimBuddy *); | |
275 | |
276 void (*convo_closed)(GaimConnection *, const char *who); | |
277 | |
278 const char *(*normalize)(const GaimAccount *, const char *); | |
279 | |
15071 | 280 void (*set_buddy_icon)(GaimConnection *, const char *cached_path); |
14192 | 281 |
282 void (*remove_group)(GaimConnection *gc, GaimGroup *group); | |
283 | |
284 char *(*get_cb_real_name)(GaimConnection *gc, int id, const char *who); | |
285 | |
286 void (*set_chat_topic)(GaimConnection *gc, int id, const char *topic); | |
287 | |
288 GaimChat *(*find_blist_chat)(GaimAccount *account, const char *name); | |
289 | |
290 /* room listing prpl callbacks */ | |
291 GaimRoomlist *(*roomlist_get_list)(GaimConnection *gc); | |
292 void (*roomlist_cancel)(GaimRoomlist *list); | |
293 void (*roomlist_expand_category)(GaimRoomlist *list, GaimRoomlistRoom *category); | |
294 | |
295 /* file transfer callbacks */ | |
296 gboolean (*can_receive_file)(GaimConnection *, const char *who); | |
297 void (*send_file)(GaimConnection *, const char *who, const char *filename); | |
298 GaimXfer *(*new_xfer)(GaimConnection *, const char *who); | |
299 gboolean (*offline_message)(const GaimBuddy *buddy); | |
300 | |
301 GaimWhiteboardPrplOps *whiteboard_prpl_ops; | |
14542 | 302 |
303 /* For use in plugins that may understand the underlying protocol */ | |
304 int (*send_raw)(GaimConnection *gc, const char *buf, int len); | |
15124 | 305 |
306 /* room list serialize */ | |
307 char *(*roomlist_room_serialize)(GaimRoomlistRoom *room); | |
14192 | 308 }; |
309 | |
310 #define GAIM_IS_PROTOCOL_PLUGIN(plugin) \ | |
311 ((plugin)->info->type == GAIM_PLUGIN_PROTOCOL) | |
312 | |
313 #define GAIM_PLUGIN_PROTOCOL_INFO(plugin) \ | |
314 ((GaimPluginProtocolInfo *)(plugin)->info->extra_info) | |
315 | |
316 #ifdef __cplusplus | |
317 extern "C" { | |
318 #endif | |
319 | |
320 /**************************************************************************/ | |
321 /** @name Protocol Plugin API */ | |
322 /**************************************************************************/ | |
323 /*@{*/ | |
324 | |
325 /** | |
326 * Notifies Gaim that an account's idle state and time have changed. | |
327 * | |
328 * This is meant to be called from protocol plugins. | |
329 * | |
330 * @param account The account. | |
331 * @param idle The user's idle state. | |
332 * @param idle_time The user's idle time. | |
333 */ | |
334 void gaim_prpl_got_account_idle(GaimAccount *account, gboolean idle, | |
335 time_t idle_time); | |
336 | |
337 /** | |
338 * Notifies Gaim of an account's log-in time. | |
339 * | |
340 * This is meant to be called from protocol plugins. | |
341 * | |
342 * @param account The account the user is on. | |
343 * @param login_time The user's log-in time. | |
344 */ | |
345 void gaim_prpl_got_account_login_time(GaimAccount *account, time_t login_time); | |
346 | |
347 /** | |
348 * Notifies Gaim that an account's status has changed. | |
349 * | |
350 * This is meant to be called from protocol plugins. | |
351 * | |
352 * @param account The account the user is on. | |
353 * @param status_id The status ID. | |
354 * @param ... A NULL-terminated list of attribute IDs and values, | |
355 * beginning with the value for @a attr_id. | |
356 */ | |
357 void gaim_prpl_got_account_status(GaimAccount *account, | |
358 const char *status_id, ...); | |
359 /** | |
360 * Notifies Gaim that a user's idle state and time have changed. | |
361 * | |
362 * This is meant to be called from protocol plugins. | |
363 * | |
364 * @param account The account the user is on. | |
365 * @param name The screen name of the user. | |
366 * @param idle The user's idle state. | |
367 * @param idle_time The user's idle time. This is the time at | |
368 * which the user became idle, in seconds since | |
369 * the epoch. | |
370 */ | |
371 void gaim_prpl_got_user_idle(GaimAccount *account, const char *name, | |
372 gboolean idle, time_t idle_time); | |
373 | |
374 /** | |
375 * Notifies Gaim of a user's log-in time. | |
376 * | |
377 * This is meant to be called from protocol plugins. | |
378 * | |
379 * @param account The account the user is on. | |
380 * @param name The screen name of the user. | |
381 * @param login_time The user's log-in time. | |
382 */ | |
383 void gaim_prpl_got_user_login_time(GaimAccount *account, const char *name, | |
384 time_t login_time); | |
385 | |
386 /** | |
387 * Notifies Gaim that a user's status has changed. | |
388 * | |
389 * This is meant to be called from protocol plugins. | |
390 * | |
391 * @param account The account the user is on. | |
392 * @param name The screen name of the user. | |
393 * @param status_id The status ID. | |
394 * @param ... A NULL-terminated list of attribute IDs and values, | |
395 * beginning with the value for @a attr_id. | |
396 */ | |
397 void gaim_prpl_got_user_status(GaimAccount *account, const char *name, | |
398 const char *status_id, ...); | |
399 /** | |
400 * Informs the server that an account's status changed. | |
401 * | |
402 * @param account The account the user is on. | |
403 * @param old_status The previous status. | |
404 * @param new_status The status that was activated, or deactivated | |
405 * (in the case of independent statuses). | |
406 */ | |
407 void gaim_prpl_change_account_status(GaimAccount *account, | |
408 GaimStatus *old_status, | |
409 GaimStatus *new_status); | |
410 | |
411 /** | |
412 * Retrieves the list of stock status types from a prpl. | |
413 * | |
414 * @param account The account the user is on. | |
415 * @param presence The presence for which we're going to get statuses | |
416 * | |
417 * @return List of statuses | |
418 */ | |
419 GList *gaim_prpl_get_statuses(GaimAccount *account, GaimPresence *presence); | |
420 | |
421 /*@}*/ | |
422 | |
423 /**************************************************************************/ | |
424 /** @name Protocol Plugin Subsystem API */ | |
425 /**************************************************************************/ | |
426 /*@{*/ | |
427 | |
428 /** | |
429 * Finds a protocol plugin structure of the specified type. | |
430 * | |
431 * @param id The protocol plugin; | |
432 */ | |
433 GaimPlugin *gaim_find_prpl(const char *id); | |
434 | |
435 /*@}*/ | |
436 | |
437 #ifdef __cplusplus | |
438 } | |
439 #endif | |
440 | |
441 #endif /* _PRPL_H_ */ |