Mercurial > pidgin3 / file comparison

comparison: libpurple/protocol.h

libpurple/protocol.h

branch
soc.2013.gobjectification.plugins
changeset 36543
a8c3fecee2d3
parent 36509
86e882c3cfdf
child 36544
1bf8b6ef5aea
equal deleted inserted replaced
36542:30f40ecc4631 36543:a8c3fecee2d3
1 /**
2 * @file protocol.h Protocol Plugin functions
3 * @ingroup core
4 */
5
6 /* purple
7 *
8 * Purple is the legal property of its developers, whose names are too numerous
9 * to list here. Please refer to the COPYRIGHT file distributed with this
10 * source distribution.
11 *
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or
15 * (at your option) any later version.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, write to the Free Software
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
25 */
26
27 /* this file should be all that prpls need to include. therefore, by including
28 * this file, they should get glib, proxy, purple_connection, prpl, etc. */
29
30 #ifndef _PURPLE_PRPL_H_
31 #define _PURPLE_PRPL_H_
32
33 typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
34
35 typedef struct _PurpleProtocolAction PurpleProtocolAction;
36
37 typedef void (*PurpleProtocolActionCallback)(PurpleProtocolAction *);
38
39 /** Represents "nudges" and "buzzes" that you may send to a buddy to attract
40 * their attention (or vice-versa).
41 */
42 typedef struct _PurpleAttentionType PurpleAttentionType;
43
44 /**************************************************************************/
45 /** @name Basic Protocol Information */
46 /**************************************************************************/
47
48 typedef enum {
49 PURPLE_ICON_SCALE_DISPLAY = 0x01, /**< We scale the icon when we display it */
50 PURPLE_ICON_SCALE_SEND = 0x02 /**< We scale the icon before we send it to the server */
51 } PurpleIconScaleRules;
52
53
54 /**
55 * A description of a Buddy Icon specification. This tells Purple what kind of image file
56 * it should give this prpl, and what kind of image file it should expect back.
57 * Dimensions less than 1 should be ignored and the image not scaled.
58 */
59 typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
60
61 /**
62 * A description of a file transfer thumbnail specification.
63 * This tells the UI if and what image formats the prpl support for file
64 * transfer thumbnails.
65 */
66 typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec;
67
68 /**
69 * This \#define exists just to make it easier to fill out the buddy icon
70 * field in the prpl info struct for protocols that couldn't care less.
71 */
72 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
73
74 #ifdef HAVE_UNISTD_H
75 #include <unistd.h>
76 #endif
77
78 #include "buddylist.h"
79 #include "conversations.h"
80 #include "ft.h"
81 #include "imgstore.h"
82 #include "media.h"
83 #include "notify.h"
84 #include "proxy.h"
85 #include "roomlist.h"
86 #include "status.h"
87 #include "whiteboard.h"
88
89
90 /** @copydoc PurpleBuddyIconSpec */
91 struct _PurpleBuddyIconSpec {
92 /** This is a comma-delimited list of image formats or @c NULL if icons
93 * are not supported. Neither the core nor the prpl will actually
94 * check to see if the data it's given matches this; it's entirely up
95 * to the UI to do what it wants
96 */
97 char *format;
98
99 int min_width; /**< Minimum width of this icon */
100 int min_height; /**< Minimum height of this icon */
101 int max_width; /**< Maximum width of this icon */
102 int max_height; /**< Maximum height of this icon */
103 size_t max_filesize; /**< Maximum size in bytes */
104 PurpleIconScaleRules scale_rules; /**< How to stretch this icon */
105 };
106
107 /** Represents an entry containing information that must be supplied by the
108 * user when joining a chat.
109 */
110 struct proto_chat_entry {
111 const char *label; /**< User-friendly name of the entry */
112 const char *identifier; /**< Used by the PRPL to identify the option */
113 gboolean required; /**< True if it's required */
114 gboolean is_int; /**< True if the entry expects an integer */
115 int min; /**< Minimum value in case of integer */
116 int max; /**< Maximum value in case of integer */
117 gboolean secret; /**< True if the entry is secret (password) */
118 };
119
120 /**
121 * Protocol options
122 *
123 * These should all be stuff that some plugins can do and others can't.
124 */
125 typedef enum
126 {
127 /**
128 * User names are unique to a chat and are not shared between rooms.
129 *
130 * XMPP lets you choose what name you want in chats, so it shouldn't
131 * be pulling the aliases from the buddy list for the chat list;
132 * it gets annoying.
133 */
134 OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
135
136 /**
137 * Chat rooms have topics.
138 *
139 * IRC and XMPP support this.
140 */
141 OPT_PROTO_CHAT_TOPIC = 0x00000008,
142
143 /**
144 * Don't require passwords for sign-in.
145 *
146 * Zephyr doesn't require passwords, so there's no
147 * need for a password prompt.
148 */
149 OPT_PROTO_NO_PASSWORD = 0x00000010,
150
151 /**
152 * Notify on new mail.
153 *
154 * MSN and Yahoo notify you when you have new mail.
155 */
156 OPT_PROTO_MAIL_CHECK = 0x00000020,
157
158 /**
159 * Images in IMs.
160 *
161 * Oscar lets you send images in direct IMs.
162 */
163 OPT_PROTO_IM_IMAGE = 0x00000040,
164
165 /**
166 * Allow passwords to be optional.
167 *
168 * Passwords in IRC are optional, and are needed for certain
169 * functionality.
170 */
171 OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
172
173 /**
174 * Allows font size to be specified in sane point size
175 *
176 * Probably just XMPP and Y!M
177 */
178 OPT_PROTO_USE_POINTSIZE = 0x00000100,
179
180 /**
181 * Set the Register button active even when the username has not
182 * been specified.
183 *
184 * Gadu-Gadu doesn't need a username to register new account (because
185 * usernames are assigned by the server).
186 */
187 OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
188
189 /**
190 * Indicates that slash commands are native to this protocol.
191 * Used as a hint that unknown commands should not be sent as messages.
192 */
193 OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
194
195 /**
196 * Indicates that this protocol supports sending a user-supplied message
197 * along with an invitation.
198 */
199 OPT_PROTO_INVITE_MESSAGE = 0x00000800,
200
201 /**
202 * Indicates that this protocol supports sending a user-supplied message
203 * along with an authorization acceptance.
204 */
205 OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE = 0x00001000,
206
207 /**
208 * Indicates that this protocol supports sending a user-supplied message
209 * along with an authorization denial.
210 */
211 OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE = 0x00002000
212
213 } PurpleProtocolOptions;
214
215 /**
216 * Represents an action that the protocol can perform. This shows up in the
217 * Accounts menu, under a submenu with the name of the account.
218 */
219 struct _PurpleProtocolAction {
220 char *label;
221 PurpleProtocolActionCallback callback;
222 PurpleConnection *connection;
223 gpointer user_data;
224 };
225
226 /**
227 * A protocol plugin information structure.
228 *
229 * Every protocol plugin initializes this structure. It is the gateway
230 * between purple and the protocol plugin. Many of these callbacks can be
231 * NULL. If a callback must be implemented, it has a comment indicating so.
232 */
233 struct _PurplePluginProtocolInfo
234 {
235 const char *id;
236 const char *name;
237
238 /**
239 * The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
240 * This allows adding more functions to this struct without requiring a major version bump.
241 */
242 unsigned long struct_size;
243
244 /* NOTE:
245 * If more functions are added, they should accessed using the following syntax:
246 *
247 * if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
248 * prpl->new_function(...);
249 *
250 * instead of
251 *
252 * if (prpl->new_function != NULL)
253 * prpl->new_function(...);
254 *
255 * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
256 * functions (e.g. login, send_im etc.) too.
257 */
258
259 PurpleProtocolOptions options; /**< Protocol options. */
260
261 GList *user_splits; /**< A GList of PurpleAccountUserSplit */
262 GList *protocol_options; /**< A GList of PurpleAccountOption */
263
264 PurpleBuddyIconSpec icon_spec; /**< The icon spec. */
265
266 /**
267 * Callback that returns the actions the protocol can perform
268 */
269 GList *(*get_actions)(PurpleConnection *);
270
271 /**
272 * Returns the base icon name for the given buddy and account.
273 * If buddy is NULL and the account is non-NULL, it will return the
274 * name to use for the account's icon. If both are NULL, it will
275 * return the name to use for the protocol's icon.
276 *
277 * This must be implemented.
278 */
279 const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
280
281 /**
282 * Fills the four char**'s with string identifiers for "emblems"
283 * that the UI will interpret and display as relevant
284 */
285 const char *(*list_emblem)(PurpleBuddy *buddy);
286
287 /**
288 * Gets a short string representing this buddy's status. This will
289 * be shown on the buddy list.
290 */
291 char *(*status_text)(PurpleBuddy *buddy);
292
293 /**
294 * Allows the prpl to add text to a buddy's tooltip.
295 */
296 void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
297
298 /**
299 * Returns a list of #PurpleStatusType which exist for this account;
300 * this must be implemented, and must add at least the offline and
301 * online states.
302 */
303 GList *(*status_types)(PurpleAccount *account);
304
305 /**
306 * Returns a list of #PurpleMenuAction structs, which represent extra
307 * actions to be shown in (for example) the right-click menu for @a
308 * node.
309 */
310 GList *(*blist_node_menu)(PurpleBlistNode *node);
311
312 /**
313 * Returns a list of #proto_chat_entry structs, which represent
314 * information required by the PRPL to join a chat. libpurple will
315 * call join_chat along with the information filled by the user.
316 *
317 * @return A list of #proto_chat_entry structs
318 */
319 GList *(*chat_info)(PurpleConnection *);
320
321 /**
322 * Returns a hashtable which maps #proto_chat_entry struct identifiers
323 * to default options as strings based on chat_name. The resulting
324 * hashtable should be created with g_hash_table_new_full(g_str_hash,
325 * g_str_equal, NULL, g_free);. Use #get_chat_name if you instead need
326 * to extract a chat name from a hashtable.
327 *
328 * @param chat_name The chat name to be turned into components
329 * @return Hashtable containing the information extracted from chat_name
330 */
331 GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
332
333 /* All the server-related functions */
334
335 /** This must be implemented. */
336 void (*login)(PurpleAccount *);
337
338 /** This must be implemented. */
339 void (*close)(PurpleConnection *);
340
341 /**
342 * This PRPL function should return a positive value on success.
343 * If the message is too big to be sent, return -E2BIG. If
344 * the account is not connected, return -ENOTCONN. If the
345 * PRPL is unable to send the message for another reason, return
346 * some other negative value. You can use one of the valid
347 * errno values, or just big something. If the message should
348 * not be echoed to the conversation window, return 0.
349 */
350 int (*send_im)(PurpleConnection *, const char *who,
351 const char *message,
352 PurpleMessageFlags flags);
353
354 void (*set_info)(PurpleConnection *, const char *info);
355
356 /**
357 * @return If this protocol requires the PURPLE_IM_TYPING message to
358 * be sent repeatedly to signify that the user is still
359 * typing, then the PRPL should return the number of
360 * seconds to wait before sending a subsequent notification.
361 * Otherwise the PRPL should return 0.
362 */
363 unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleIMTypingState state);
364
365 /**
366 * Should arrange for purple_notify_userinfo() to be called with
367 * @a who's user info.
368 */
369 void (*get_info)(PurpleConnection *, const char *who);
370 void (*set_status)(PurpleAccount *account, PurpleStatus *status);
371
372 void (*set_idle)(PurpleConnection *, int idletime);
373 void (*change_passwd)(PurpleConnection *, const char *old_pass,
374 const char *new_pass);
375
376 /**
377 * Add a buddy to a group on the server.
378 *
379 * This PRPL function may be called in situations in which the buddy is
380 * already in the specified group. If the protocol supports
381 * authorization and the user is not already authorized to see the
382 * status of \a buddy, \a add_buddy should request authorization.
383 *
384 * If authorization is required, then use the supplied invite message.
385 */
386 void (*add_buddy)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
387 void (*add_buddies)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
388 void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
389 void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
390 void (*add_permit)(PurpleConnection *, const char *name);
391 void (*add_deny)(PurpleConnection *, const char *name);
392 void (*rem_permit)(PurpleConnection *, const char *name);
393 void (*rem_deny)(PurpleConnection *, const char *name);
394 void (*set_permit_deny)(PurpleConnection *);
395
396 /**
397 * Called when the user requests joining a chat. Should arrange for
398 * #serv_got_joined_chat to be called.
399 *
400 * @param components A hashtable containing information required to
401 * join the chat as described by the entries returned
402 * by #chat_info. It may also be called when accepting
403 * an invitation, in which case this matches the
404 * data parameter passed to #serv_got_chat_invite.
405 */
406 void (*join_chat)(PurpleConnection *, GHashTable *components);
407
408 /**
409 * Called when the user refuses a chat invitation.
410 *
411 * @param components A hashtable containing information required to
412 * join the chat as passed to #serv_got_chat_invite.
413 */
414 void (*reject_chat)(PurpleConnection *, GHashTable *components);
415
416 /**
417 * Returns a chat name based on the information in components. Use
418 * #chat_info_defaults if you instead need to generate a hashtable
419 * from a chat name.
420 *
421 * @param components A hashtable containing information about the chat.
422 */
423 char *(*get_chat_name)(GHashTable *components);
424
425 /**
426 * Invite a user to join a chat.
427 *
428 * @param id The id of the chat to invite the user to.
429 * @param message A message displayed to the user when the invitation
430 * is received.
431 * @param who The name of the user to send the invation to.
432 */
433 void (*chat_invite)(PurpleConnection *, int id,
434 const char *message, const char *who);
435 /**
436 * Called when the user requests leaving a chat.
437 *
438 * @param id The id of the chat to leave
439 */
440 void (*chat_leave)(PurpleConnection *, int id);
441
442 /**
443 * Send a whisper to a user in a chat.
444 *
445 * @param id The id of the chat.
446 * @param who The name of the user to send the whisper to.
447 * @param message The message of the whisper.
448 */
449 void (*chat_whisper)(PurpleConnection *, int id,
450 const char *who, const char *message);
451
452 /**
453 * Send a message to a chat.
454 * This PRPL function should return a positive value on success.
455 * If the message is too big to be sent, return -E2BIG. If
456 * the account is not connected, return -ENOTCONN. If the
457 * PRPL is unable to send the message for another reason, return
458 * some other negative value. You can use one of the valid
459 * errno values, or just big something.
460 *
461 * @param id The id of the chat to send the message to.
462 * @param message The message to send to the chat.
463 * @param flags A bitwise OR of #PurpleMessageFlags representing
464 * message flags.
465 * @return A positive number or 0 in case of success,
466 * a negative error number in case of failure.
467 */
468 int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
469
470 /** If implemented, this will be called regularly for this prpl's
471 * active connections. You'd want to do this if you need to repeatedly
472 * send some kind of keepalive packet to the server to avoid being
473 * disconnected. ("Regularly" is defined by
474 * <code>KEEPALIVE_INTERVAL</code> in <tt>libpurple/connection.c</tt>.)
475 */
476 void (*keepalive)(PurpleConnection *);
477
478 /** new user registration */
479 void (*register_user)(PurpleAccount *);
480
481 /**
482 * @deprecated Use #PurplePluginProtocolInfo.get_info instead.
483 */
484 void (*get_cb_info)(PurpleConnection *, int, const char *who);
485
486 /** save/store buddy's alias on server list/roster */
487 void (*alias_buddy)(PurpleConnection *, const char *who,
488 const char *alias);
489
490 /** change a buddy's group on a server list/roster */
491 void (*group_buddy)(PurpleConnection *, const char *who,
492 const char *old_group, const char *new_group);
493
494 /** rename a group on a server list/roster */
495 void (*rename_group)(PurpleConnection *, const char *old_name,
496 PurpleGroup *group, GList *moved_buddies);
497
498 void (*buddy_free)(PurpleBuddy *);
499
500 void (*convo_closed)(PurpleConnection *, const char *who);
501
502 /**
503 * Convert the username @a who to its canonical form. Also checks for
504 * validity.
505 *
506 * For example, AIM treats "fOo BaR" and "foobar" as the same user; this
507 * function should return the same normalized string for both of those.
508 * On the other hand, both of these are invalid for protocols with
509 * number-based usernames, so function should return NULL in such case.
510 *
511 * @param account The account the username is related to. Can
512 * be NULL.
513 * @param who The username to convert.
514 * @return Normalized username, or NULL, if it's invalid.
515 */
516 const char *(*normalize)(const PurpleAccount *account, const char *who);
517
518 /**
519 * Set the buddy icon for the given connection to @a img. The prpl
520 * does NOT own a reference to @a img; if it needs one, it must
521 * #purple_imgstore_ref(@a img) itself.
522 */
523 void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
524
525 void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
526
527 /** Gets the real name of a participant in a chat. For example, on
528 * XMPP this turns a chat room nick <tt>foo</tt> into
529 * <tt>room\@server/foo</tt>
530 * @param gc the connection on which the room is.
531 * @param id the ID of the chat room.
532 * @param who the nickname of the chat participant.
533 * @return the real name of the participant. This string must be
534 * freed by the caller.
535 */
536 char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
537
538 void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
539
540 PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
541
542 /* room listing prpl callbacks */
543 PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
544 void (*roomlist_cancel)(PurpleRoomlist *list);
545 void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
546
547 /* file transfer callbacks */
548 gboolean (*can_receive_file)(PurpleConnection *, const char *who);
549 void (*send_file)(PurpleConnection *, const char *who, const char *filename);
550 PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
551
552 /** Checks whether offline messages to @a buddy are supported.
553 * @return @c TRUE if @a buddy can be sent messages while they are
554 * offline, or @c FALSE if not.
555 */
556 gboolean (*offline_message)(const PurpleBuddy *buddy);
557
558 PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
559
560 /** For use in plugins that may understand the underlying protocol */
561 int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
562
563 /* room list serialize */
564 char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
565
566 /** Remove the user from the server. The account can either be
567 * connected or disconnected. After the removal is finished, the
568 * connection will stay open and has to be closed!
569 */
570 /* This is here rather than next to register_user for API compatibility
571 * reasons.
572 */
573 void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
574
575 /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
576 gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
577 GList *(*get_attention_types)(PurpleAccount *acct);
578
579 /** This allows protocols to specify additional strings to be used for
580 * various purposes. The idea is to stuff a bunch of strings in this hash
581 * table instead of expanding the struct for every addition. This hash
582 * table is allocated every call and MUST be unrefed by the caller.
583 *
584 * @param account The account to specify. This can be NULL.
585 * @return The protocol's string hash table. The hash table should be
586 * destroyed by the caller when it's no longer needed.
587 */
588 GHashTable *(*get_account_text_table)(PurpleAccount *account);
589
590 /**
591 * Initiate a media session with the given contact.
592 *
593 * @param account The account to initiate the media session on.
594 * @param who The remote user to initiate the session with.
595 * @param type The type of media session to initiate.
596 * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
597 */
598 gboolean (*initiate_media)(PurpleAccount *account, const char *who,
599 PurpleMediaSessionType type);
600
601 /**
602 * Checks to see if the given contact supports the given type of media session.
603 *
604 * @param account The account the contact is on.
605 * @param who The remote user to check for media capability with.
606 * @return The media caps the contact supports.
607 */
608 PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
609 const char *who);
610
611 /**
612 * Returns an array of "PurpleMood"s, with the last one having
613 * "mood" set to @c NULL.
614 */
615 PurpleMood *(*get_moods)(PurpleAccount *account);
616
617 /**
618 * Set the user's "friendly name" (or alias or nickname or
619 * whatever term you want to call it) on the server. The
620 * protocol plugin should call success_cb or failure_cb
621 * *asynchronously* (if it knows immediately that the set will fail,
622 * call one of the callbacks from an idle/0-second timeout) depending
623 * on if the nickname is set successfully.
624 *
625 * @param gc The connection for which to set an alias
626 * @param alias The new server-side alias/nickname for this account,
627 * or NULL to unset the alias/nickname (or return it to
628 * a protocol-specific "default").
629 * @param success_cb Callback to be called if the public alias is set
630 * @param failure_cb Callback to be called if setting the public alias
631 * fails
632 * @see purple_account_set_public_alias
633 */
634 void (*set_public_alias)(PurpleConnection *gc, const char *alias,
635 PurpleSetPublicAliasSuccessCallback success_cb,
636 PurpleSetPublicAliasFailureCallback failure_cb);
637 /**
638 * Retrieve the user's "friendly name" as set on the server.
639 * The protocol plugin should call success_cb or failure_cb
640 * *asynchronously* (even if it knows immediately that the get will fail,
641 * call one of the callbacks from an idle/0-second timeout) depending
642 * on if the nickname is retrieved.
643 *
644 * @param gc The connection for which to retireve the alias
645 * @param success_cb Callback to be called with the retrieved alias
646 * @param failure_cb Callback to be called if the prpl is unable to
647 * retrieve the alias
648 * @see purple_account_get_public_alias
649 */
650 void (*get_public_alias)(PurpleConnection *gc,
651 PurpleGetPublicAliasSuccessCallback success_cb,
652 PurpleGetPublicAliasFailureCallback failure_cb);
653 };
654
655 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
656 (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size && \
657 prpl->member != NULL)
658
659 G_BEGIN_DECLS
660
661 /**************************************************************************/
662 /** @name Attention Type API */
663 /**************************************************************************/
664 /*@{*/
665
666 /**
667 * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
668 *
669 * @param ulname A non-localized string that can be used by UIs in need of such
670 * non-localized strings. This should be the same as @a name,
671 * without localization.
672 * @param name A localized string that the UI may display for the event. This
673 * should be the same string as @a ulname, with localization.
674 * @param inc_desc A localized description shown when the event is received.
675 * @param out_desc A localized description shown when the event is sent.
676 *
677 * @return A pointer to the new object.
678 */
679 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
680 const char *inc_desc, const char *out_desc);
681
682 /**
683 * Sets the displayed name of the attention-demanding event.
684 *
685 * @param type The attention type.
686 * @param name The localized name that will be displayed by UIs. This should be
687 * the same string given as the unlocalized name, but with
688 * localization.
689 */
690 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
691
692 /**
693 * Sets the description of the attention-demanding event shown in conversations
694 * when the event is received.
695 *
696 * @param type The attention type.
697 * @param desc The localized description for incoming events.
698 */
699 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
700
701 /**
702 * Sets the description of the attention-demanding event shown in conversations
703 * when the event is sent.
704 *
705 * @param type The attention type.
706 * @param desc The localized description for outgoing events.
707 */
708 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
709
710 /**
711 * Sets the name of the icon to display for the attention event; this is optional.
712 *
713 * @param type The attention type.
714 * @param name The icon's name.
715 * @note Icons are optional for attention events.
716 */
717 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
718
719 /**
720 * Sets the unlocalized name of the attention event; some UIs may need this,
721 * thus it is required.
722 *
723 * @param type The attention type.
724 * @param ulname The unlocalized name. This should be the same string given as
725 * the localized name, but without localization.
726 */
727 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
728
729 /**
730 * Get the attention type's name as displayed by the UI.
731 *
732 * @param type The attention type.
733 *
734 * @return The name.
735 */
736 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
737
738 /**
739 * Get the attention type's description shown when the event is received.
740 *
741 * @param type The attention type.
742 * @return The description.
743 */
744 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
745
746 /**
747 * Get the attention type's description shown when the event is sent.
748 *
749 * @param type The attention type.
750 * @return The description.
751 */
752 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
753
754 /**
755 * Get the attention type's icon name.
756 *
757 * @param type The attention type.
758 * @return The icon name or @c NULL if unset/empty.
759 * @note Icons are optional for attention events.
760 */
761 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
762
763 /**
764 * Get the attention type's unlocalized name; this is useful for some UIs.
765 *
766 * @param type The attention type
767 * @return The unlocalized name.
768 */
769 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
770
771 /*@}*/
772
773 /**************************************************************************/
774 /** @name Protocol Plugin API */
775 /**************************************************************************/
776 /*@{*/
777
778 /**
779 * Notifies Purple that our account's idle state and time have changed.
780 *
781 * This is meant to be called from protocol plugins.
782 *
783 * @param account The account.
784 * @param idle The user's idle state.
785 * @param idle_time The user's idle time.
786 */
787 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
788 time_t idle_time);
789
790 /**
791 * Notifies Purple of our account's log-in time.
792 *
793 * This is meant to be called from protocol plugins.
794 *
795 * @param account The account the user is on.
796 * @param login_time The user's log-in time.
797 */
798 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
799
800 /**
801 * Notifies Purple that our account's status has changed.
802 *
803 * This is meant to be called from protocol plugins.
804 *
805 * @param account The account the user is on.
806 * @param status_id The status ID.
807 * @param ... A NULL-terminated list of attribute IDs and values,
808 * beginning with the value for @a attr_id.
809 */
810 void purple_prpl_got_account_status(PurpleAccount *account,
811 const char *status_id, ...) G_GNUC_NULL_TERMINATED;
812
813 /**
814 * Notifies Purple that our account's actions have changed. This is only
815 * called after the initial connection. Emits the account-actions-changed
816 * signal.
817 *
818 * This is meant to be called from protocol plugins.
819 *
820 * @param account The account.
821 *
822 * @see account-actions-changed
823 */
824 void purple_prpl_got_account_actions(PurpleAccount *account);
825
826 /**
827 * Notifies Purple that a buddy's idle state and time have changed.
828 *
829 * This is meant to be called from protocol plugins.
830 *
831 * @param account The account the user is on.
832 * @param name The name of the buddy.
833 * @param idle The user's idle state.
834 * @param idle_time The user's idle time. This is the time at
835 * which the user became idle, in seconds since
836 * the epoch. If the PRPL does not know this value
837 * then it should pass 0.
838 */
839 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
840 gboolean idle, time_t idle_time);
841
842 /**
843 * Notifies Purple of a buddy's log-in time.
844 *
845 * This is meant to be called from protocol plugins.
846 *
847 * @param account The account the user is on.
848 * @param name The name of the buddy.
849 * @param login_time The user's log-in time.
850 */
851 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
852 time_t login_time);
853
854 /**
855 * Notifies Purple that a buddy's status has been activated.
856 *
857 * This is meant to be called from protocol plugins.
858 *
859 * @param account The account the user is on.
860 * @param name The name of the buddy.
861 * @param status_id The status ID.
862 * @param ... A NULL-terminated list of attribute IDs and values,
863 * beginning with the value for @a attr_id.
864 */
865 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
866 const char *status_id, ...) G_GNUC_NULL_TERMINATED;
867
868 /**
869 * Notifies libpurple that a buddy's status has been deactivated
870 *
871 * This is meant to be called from protocol plugins.
872 *
873 * @param account The account the user is on.
874 * @param name The name of the buddy.
875 * @param status_id The status ID.
876 */
877 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
878 const char *status_id);
879
880 /**
881 * Informs the server that our account's status changed.
882 *
883 * @param account The account the user is on.
884 * @param old_status The previous status.
885 * @param new_status The status that was activated, or deactivated
886 * (in the case of independent statuses).
887 */
888 void purple_prpl_change_account_status(PurpleAccount *account,
889 PurpleStatus *old_status,
890 PurpleStatus *new_status);
891
892 /**
893 * Retrieves the list of stock status types from a prpl.
894 *
895 * @param account The account the user is on.
896 * @param presence The presence for which we're going to get statuses
897 *
898 * @return List of statuses
899 */
900 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
901
902 /**
903 * Send an attention request message.
904 *
905 * @param gc The connection to send the message on.
906 * @param who Whose attention to request.
907 * @param type_code An index into the prpl's attention_types list determining the type
908 * of the attention request command to send. 0 if prpl only defines one
909 * (for example, Yahoo and MSN), but some protocols define more (MySpaceIM).
910 *
911 * Note that you can't send arbitrary PurpleAttentionType's, because there is
912 * only a fixed set of attention commands.
913 */
914 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
915
916 /**
917 * Process an incoming attention message.
918 *
919 * @param gc The connection that received the attention message.
920 * @param who Who requested your attention.
921 * @param type_code An index into the prpl's attention_types list determining the type
922 * of the attention request command to send.
923 */
924 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
925
926 /**
927 * Process an incoming attention message in a chat.
928 *
929 * @param gc The connection that received the attention message.
930 * @param id The chat id.
931 * @param who Who requested your attention.
932 * @param type_code An index into the prpl's attention_types list determining the type
933 * of the attention request command to send.
934 */
935 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
936
937 /**
938 * Determines if the contact supports the given media session type.
939 *
940 * @param account The account the user is on.
941 * @param who The name of the contact to check capabilities for.
942 *
943 * @return The media caps the contact supports.
944 */
945 PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
946 const char *who);
947
948 /**
949 * Initiates a media session with the given contact.
950 *
951 * @param account The account the user is on.
952 * @param who The name of the contact to start a session with.
953 * @param type The type of media session to start.
954 *
955 * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
956 */
957 gboolean purple_prpl_initiate_media(PurpleAccount *account,
958 const char *who,
959 PurpleMediaSessionType type);
960
961 /**
962 * Signals that the prpl received capabilities for the given contact.
963 *
964 * This function is intended to be used only by prpls.
965 *
966 * @param account The account the user is on.
967 * @param who The name of the contact for which capabilities have been received.
968 */
969 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
970
971 /** TODO A sanity check is needed
972 * Allocates and returns a new PurpleProtocolAction. Use this to add actions in
973 * a list in the get_actions function of the protocol.
974 *
975 * @param label The description of the action to show to the user.
976 * @param callback The callback to call when the user selects this action.
977 */
978 PurpleProtocolAction *purple_protocol_action_new(const char* label,
979 PurpleProtocolActionCallback callback);
980
981 /** TODO A sanity check is needed
982 * Frees a PurpleProtocolAction
983 *
984 * @param action The PurpleProtocolAction to free.
985 */
986 void purple_protocol_action_free(PurpleProtocolAction *action);
987
988 /**************************************************************************/
989 /** @name Protocols API */
990 /**************************************************************************/
991 /*@{*/
992
993 /**
994 * Finds a protocol plugin info structure by ID.
995 *
996 * @param id The protocol's ID.
997 */
998 PurplePluginProtocolInfo *purple_find_protocol_info(const char *id);
999
1000 /** TODO A sanity check is needed
1001 * Adds a protocol to the list of protocols.
1002 *
1003 * @param prpl_info The protocol to add.
1004 *
1005 * @return TRUE if the protocol was added, else FALSE.
1006 */
1007 gboolean purple_protocols_add(PurplePluginProtocolInfo *prpl_info);
1008
1009 /** TODO A sanity check is needed
1010 * Removes a protocol from the list of protocols. This will disconnect all
1011 * connected accounts using this protocol, and free the protocol's user splits
1012 * and protocol options.
1013 *
1014 * @param prpl_info The protocol to remove.
1015 *
1016 * @return TRUE if the protocol was removed, else FALSE.
1017 */
1018 gboolean purple_protocols_remove(PurplePluginProtocolInfo *prpl_info);
1019
1020 /** TODO A sanity check is needed
1021 * Returns a list of all loaded protocols.
1022 *
1023 * @constreturn A list of all loaded protocols.
1024 */
1025 GList *purple_protocols_get_all(void);
1026
1027 /*@}*/
1028
1029 /**************************************************************************/
1030 /** @name Protocols Subsytem API */
1031 /**************************************************************************/
1032 /*@{*/
1033
1034 /**
1035 * Initializes the protocols subsystem.
1036 */
1037 void purple_protocols_init(void);
1038
1039 /** TODO Make protocols use this handle, instead of plugins handle
1040 * Returns the protocols subsystem handle.
1041 *
1042 * @return The protocols subsystem handle.
1043 */
1044 void *purple_protocols_get_handle(void);
1045
1046 /**
1047 * Uninitializes the protocols subsystem.
1048 */
1049 void purple_protocols_uninit(void);
1050
1051 /*@}*/
1052
1053 G_END_DECLS
1054
1055 #endif /* _PRPL_H_ */

Mercurial Repository: pidgin3

mercurial