Mercurial > pidgin
annotate libgaim/prpl.h @ 14942:77ca54a3af31
[gaim-migrate @ 17714]
Also print the error to the console.
committer: Tailor Script <tailor@pidgin.im>
author | Daniel Atallah <daniel.atallah@gmail.com> |
---|---|
date | Thu, 09 Nov 2006 20:21:13 +0000 |
parents | 28c7e23bcc7e |
children | c0d6f960675b |
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. | |
14940
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" | |
69 #include "proxy.h" | |
70 #include "plugin.h" | |
71 #include "roomlist.h" | |
72 #include "status.h" | |
73 #include "whiteboard.h" | |
74 | |
75 struct proto_chat_entry { | |
76 const char *label; | |
77 const char *identifier; | |
78 gboolean required; | |
79 gboolean is_int; | |
80 int min; | |
81 int max; | |
82 gboolean secret; | |
83 }; | |
84 | |
85 /** | |
86 * Protocol options | |
87 * | |
88 * These should all be stuff that some plugins can do and others can't. | |
89 */ | |
90 typedef enum | |
91 { | |
92 /** | |
93 * Use a unique name, not an alias, for chat rooms. | |
94 * | |
95 * Jabber lets you choose what name you want for chat. | |
96 * So it shouldn't be pulling the alias for when you're in chat; | |
97 * it gets annoying. | |
98 */ | |
99 OPT_PROTO_UNIQUE_CHATNAME = 0x00000004, | |
100 | |
101 /** | |
102 * Chat rooms have topics. | |
103 * | |
104 * IRC and Jabber support this. | |
105 */ | |
106 OPT_PROTO_CHAT_TOPIC = 0x00000008, | |
107 | |
108 /** | |
109 * Don't require passwords for sign-in. | |
110 * | |
111 * Zephyr doesn't require passwords, so there's no | |
112 * need for a password prompt. | |
113 */ | |
114 OPT_PROTO_NO_PASSWORD = 0x00000010, | |
115 | |
116 /** | |
117 * Notify on new mail. | |
118 * | |
119 * MSN and Yahoo notify you when you have new mail. | |
120 */ | |
121 OPT_PROTO_MAIL_CHECK = 0x00000020, | |
122 | |
123 /** | |
124 * Images in IMs. | |
125 * | |
126 * Oscar lets you send images in direct IMs. | |
127 */ | |
128 OPT_PROTO_IM_IMAGE = 0x00000040, | |
129 | |
130 /** | |
131 * Allow passwords to be optional. | |
132 * | |
133 * Passwords in IRC are optional, and are needed for certain | |
134 * functionality. | |
135 */ | |
136 OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080, | |
137 | |
138 /** | |
139 * Allows font size to be specified in sane point size | |
140 * | |
141 * Probably just Jabber and Y!M | |
142 */ | |
143 OPT_PROTO_USE_POINTSIZE = 0x00000100, | |
144 | |
145 /** | |
146 * Set the Register button active when screenname is not given. | |
147 * | |
148 * Gadu-Gadu doesn't need a screenname to register new account. | |
149 */ | |
150 OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200, | |
151 | |
152 } GaimProtocolOptions; | |
153 | |
154 /** | |
155 * A protocol plugin information structure. | |
156 * | |
157 * Every protocol plugin initializes this structure. It is the gateway | |
158 * between gaim and the protocol plugin. Many of this callbacks can be | |
159 * NULL. If a callback must be implemented, it has a comment indicating so. | |
160 */ | |
161 struct _GaimPluginProtocolInfo | |
162 { | |
163 GaimProtocolOptions options; /**< Protocol options. */ | |
164 | |
165 GList *user_splits; /* A GList of GaimAccountUserSplit */ | |
166 GList *protocol_options; /* A GList of GaimAccountOption */ | |
167 | |
168 GaimBuddyIconSpec icon_spec; /* The icon spec. */ | |
169 | |
170 /** | |
171 * Returns the base icon name for the given buddy and account. | |
172 * If buddy is NULL, it will return the name to use for the account's | |
173 * icon. This must be implemented. | |
174 */ | |
175 const char *(*list_icon)(GaimAccount *account, GaimBuddy *buddy); | |
176 | |
177 /** | |
178 * Fills the four char**'s with string identifiers for "emblems" | |
179 * that the UI will interpret and display as relevant | |
180 */ | |
181 void (*list_emblems)(GaimBuddy *buddy, const char **se, const char **sw, | |
182 const char **nw, const char **ne); | |
183 | |
184 /** | |
185 * Gets a short string representing this buddy's status. This will | |
186 * be shown on the buddy list. | |
187 */ | |
188 char *(*status_text)(GaimBuddy *buddy); | |
189 | |
190 /** | |
191 * Allows the prpl to add text to a buddy's tooltip. | |
192 */ | |
193 void (*tooltip_text)(GaimBuddy *buddy, GString *str, gboolean full); | |
194 | |
195 /** | |
196 * This must be implemented, and must add at least the offline | |
197 * and online states. | |
198 */ | |
199 GList *(*status_types)(GaimAccount *account); | |
200 | |
201 GList *(*blist_node_menu)(GaimBlistNode *node); | |
202 GList *(*chat_info)(GaimConnection *); | |
203 GHashTable *(*chat_info_defaults)(GaimConnection *, const char *chat_name); | |
204 | |
205 /* All the server-related functions */ | |
206 | |
207 /** This must be implemented. */ | |
208 void (*login)(GaimAccount *); | |
209 | |
210 /** This must be implemented. */ | |
211 void (*close)(GaimConnection *); | |
212 | |
213 /** | |
214 * This PRPL function should return a positive value on success. | |
215 * If the message is too big to be sent, return -E2BIG. If | |
216 * the account is not connected, return -ENOTCONN. If the | |
217 * PRPL is unable to send the message for another reason, return | |
218 * some other negative value. You can use one of the valid | |
219 * errno values, or just big something. If the message should | |
220 * not be echoed to the conversation window, return 0. | |
221 */ | |
222 int (*send_im)(GaimConnection *, const char *who, | |
223 const char *message, | |
224 GaimMessageFlags flags); | |
225 | |
226 void (*set_info)(GaimConnection *, const char *info); | |
227 unsigned int (*send_typing)(GaimConnection *, const char *name, GaimTypingState state); | |
228 void (*get_info)(GaimConnection *, const char *who); | |
229 void (*set_status)(GaimAccount *account, GaimStatus *status); | |
230 | |
231 void (*set_idle)(GaimConnection *, int idletime); | |
232 void (*change_passwd)(GaimConnection *, const char *old_pass, | |
233 const char *new_pass); | |
234 void (*add_buddy)(GaimConnection *, GaimBuddy *buddy, GaimGroup *group); | |
235 void (*add_buddies)(GaimConnection *, GList *buddies, GList *groups); | |
236 void (*remove_buddy)(GaimConnection *, GaimBuddy *buddy, GaimGroup *group); | |
237 void (*remove_buddies)(GaimConnection *, GList *buddies, GList *groups); | |
238 void (*add_permit)(GaimConnection *, const char *name); | |
239 void (*add_deny)(GaimConnection *, const char *name); | |
240 void (*rem_permit)(GaimConnection *, const char *name); | |
241 void (*rem_deny)(GaimConnection *, const char *name); | |
242 void (*set_permit_deny)(GaimConnection *); | |
243 void (*join_chat)(GaimConnection *, GHashTable *components); | |
244 void (*reject_chat)(GaimConnection *, GHashTable *components); | |
245 char *(*get_chat_name)(GHashTable *components); | |
246 void (*chat_invite)(GaimConnection *, int id, | |
247 const char *who, const char *message); | |
248 void (*chat_leave)(GaimConnection *, int id); | |
249 void (*chat_whisper)(GaimConnection *, int id, | |
250 const char *who, const char *message); | |
251 int (*chat_send)(GaimConnection *, int id, const char *message, GaimMessageFlags flags); | |
252 void (*keepalive)(GaimConnection *); | |
253 | |
254 /* new user registration */ | |
255 void (*register_user)(GaimAccount *); | |
256 | |
257 /* get "chat buddy" info and away message */ | |
258 void (*get_cb_info)(GaimConnection *, int, const char *who); | |
259 void (*get_cb_away)(GaimConnection *, int, const char *who); | |
260 | |
261 /* save/store buddy's alias on server list/roster */ | |
262 void (*alias_buddy)(GaimConnection *, const char *who, | |
263 const char *alias); | |
264 | |
265 /* change a buddy's group on a server list/roster */ | |
266 void (*group_buddy)(GaimConnection *, const char *who, | |
267 const char *old_group, const char *new_group); | |
268 | |
269 /* rename a group on a server list/roster */ | |
270 void (*rename_group)(GaimConnection *, const char *old_name, | |
271 GaimGroup *group, GList *moved_buddies); | |
272 | |
273 void (*buddy_free)(GaimBuddy *); | |
274 | |
275 void (*convo_closed)(GaimConnection *, const char *who); | |
276 | |
277 const char *(*normalize)(const GaimAccount *, const char *); | |
278 | |
279 void (*set_buddy_icon)(GaimConnection *, const char *filename); | |
280 | |
281 void (*remove_group)(GaimConnection *gc, GaimGroup *group); | |
282 | |
283 char *(*get_cb_real_name)(GaimConnection *gc, int id, const char *who); | |
284 | |
285 void (*set_chat_topic)(GaimConnection *gc, int id, const char *topic); | |
286 | |
287 GaimChat *(*find_blist_chat)(GaimAccount *account, const char *name); | |
288 | |
289 /* room listing prpl callbacks */ | |
290 GaimRoomlist *(*roomlist_get_list)(GaimConnection *gc); | |
291 void (*roomlist_cancel)(GaimRoomlist *list); | |
292 void (*roomlist_expand_category)(GaimRoomlist *list, GaimRoomlistRoom *category); | |
293 | |
294 /* file transfer callbacks */ | |
295 gboolean (*can_receive_file)(GaimConnection *, const char *who); | |
296 void (*send_file)(GaimConnection *, const char *who, const char *filename); | |
297 GaimXfer *(*new_xfer)(GaimConnection *, const char *who); | |
298 gboolean (*offline_message)(const GaimBuddy *buddy); | |
299 | |
300 GaimWhiteboardPrplOps *whiteboard_prpl_ops; | |
14542 | 301 |
302 /* For use in plugins that may understand the underlying protocol */ | |
303 int (*send_raw)(GaimConnection *gc, const char *buf, int len); | |
14192 | 304 }; |
305 | |
306 #define GAIM_IS_PROTOCOL_PLUGIN(plugin) \ | |
307 ((plugin)->info->type == GAIM_PLUGIN_PROTOCOL) | |
308 | |
309 #define GAIM_PLUGIN_PROTOCOL_INFO(plugin) \ | |
310 ((GaimPluginProtocolInfo *)(plugin)->info->extra_info) | |
311 | |
312 #ifdef __cplusplus | |
313 extern "C" { | |
314 #endif | |
315 | |
316 /**************************************************************************/ | |
317 /** @name Protocol Plugin API */ | |
318 /**************************************************************************/ | |
319 /*@{*/ | |
320 | |
321 /** | |
322 * Notifies Gaim that an account's idle state and time have changed. | |
323 * | |
324 * This is meant to be called from protocol plugins. | |
325 * | |
326 * @param account The account. | |
327 * @param idle The user's idle state. | |
328 * @param idle_time The user's idle time. | |
329 */ | |
330 void gaim_prpl_got_account_idle(GaimAccount *account, gboolean idle, | |
331 time_t idle_time); | |
332 | |
333 /** | |
334 * Notifies Gaim of an account's log-in time. | |
335 * | |
336 * This is meant to be called from protocol plugins. | |
337 * | |
338 * @param account The account the user is on. | |
339 * @param login_time The user's log-in time. | |
340 */ | |
341 void gaim_prpl_got_account_login_time(GaimAccount *account, time_t login_time); | |
342 | |
343 /** | |
344 * Notifies Gaim that an account's status has changed. | |
345 * | |
346 * This is meant to be called from protocol plugins. | |
347 * | |
348 * @param account The account the user is on. | |
349 * @param status_id The status ID. | |
350 * @param ... A NULL-terminated list of attribute IDs and values, | |
351 * beginning with the value for @a attr_id. | |
352 */ | |
353 void gaim_prpl_got_account_status(GaimAccount *account, | |
354 const char *status_id, ...); | |
355 /** | |
356 * Notifies Gaim that a user's idle state and time have changed. | |
357 * | |
358 * This is meant to be called from protocol plugins. | |
359 * | |
360 * @param account The account the user is on. | |
361 * @param name The screen name of the user. | |
362 * @param idle The user's idle state. | |
363 * @param idle_time The user's idle time. This is the time at | |
364 * which the user became idle, in seconds since | |
365 * the epoch. | |
366 */ | |
367 void gaim_prpl_got_user_idle(GaimAccount *account, const char *name, | |
368 gboolean idle, time_t idle_time); | |
369 | |
370 /** | |
371 * Notifies Gaim of a user's log-in time. | |
372 * | |
373 * This is meant to be called from protocol plugins. | |
374 * | |
375 * @param account The account the user is on. | |
376 * @param name The screen name of the user. | |
377 * @param login_time The user's log-in time. | |
378 */ | |
379 void gaim_prpl_got_user_login_time(GaimAccount *account, const char *name, | |
380 time_t login_time); | |
381 | |
382 /** | |
383 * Notifies Gaim that a user's status has changed. | |
384 * | |
385 * This is meant to be called from protocol plugins. | |
386 * | |
387 * @param account The account the user is on. | |
388 * @param name The screen name of the user. | |
389 * @param status_id The status ID. | |
390 * @param ... A NULL-terminated list of attribute IDs and values, | |
391 * beginning with the value for @a attr_id. | |
392 */ | |
393 void gaim_prpl_got_user_status(GaimAccount *account, const char *name, | |
394 const char *status_id, ...); | |
395 /** | |
396 * Informs the server that an account's status changed. | |
397 * | |
398 * @param account The account the user is on. | |
399 * @param old_status The previous status. | |
400 * @param new_status The status that was activated, or deactivated | |
401 * (in the case of independent statuses). | |
402 */ | |
403 void gaim_prpl_change_account_status(GaimAccount *account, | |
404 GaimStatus *old_status, | |
405 GaimStatus *new_status); | |
406 | |
407 /** | |
408 * Retrieves the list of stock status types from a prpl. | |
409 * | |
410 * @param account The account the user is on. | |
411 * @param presence The presence for which we're going to get statuses | |
412 * | |
413 * @return List of statuses | |
414 */ | |
415 GList *gaim_prpl_get_statuses(GaimAccount *account, GaimPresence *presence); | |
416 | |
417 /*@}*/ | |
418 | |
419 /**************************************************************************/ | |
420 /** @name Protocol Plugin Subsystem API */ | |
421 /**************************************************************************/ | |
422 /*@{*/ | |
423 | |
424 /** | |
425 * Finds a protocol plugin structure of the specified type. | |
426 * | |
427 * @param id The protocol plugin; | |
428 */ | |
429 GaimPlugin *gaim_find_prpl(const char *id); | |
430 | |
431 /*@}*/ | |
432 | |
433 #ifdef __cplusplus | |
434 } | |
435 #endif | |
436 | |
437 #endif /* _PRPL_H_ */ |