I think this was accidentally changed in revision
[pidgin-git.git] / libpurple / prpl.h
blobf3a2877fce7b19aacd425f2aeb8406b9bd9ec5b3
1 /**
2 * @file prpl.h Protocol Plugin functions
3 * @ingroup core
4 */
6 /* purple
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.
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.
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.
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
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. */
30 #ifndef _PURPLE_PRPL_H_
31 #define _PURPLE_PRPL_H_
33 typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
34 /** @copydoc _PurpleAttentionType */
35 typedef struct _PurpleAttentionType PurpleAttentionType;
37 /**************************************************************************/
38 /** @name Basic Protocol Information */
39 /**************************************************************************/
41 typedef enum {
42 PURPLE_ICON_SCALE_DISPLAY = 0x01, /**< We scale the icon when we display it */
43 PURPLE_ICON_SCALE_SEND = 0x02 /**< We scale the icon before we send it to the server */
44 } PurpleIconScaleRules;
47 /**
48 * A description of a Buddy Icon specification. This tells Purple what kind of image file
49 * it should give this prpl, and what kind of image file it should expect back.
50 * Dimensions less than 1 should be ignored and the image not scaled.
52 typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
54 /**
55 * A description of a file transfer thumbnail specification.
56 * This tells the UI if and what image formats the prpl support for file
57 * transfer thumbnails.
59 typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec;
61 /**
62 * This \#define exists just to make it easier to fill out the buddy icon
63 * field in the prpl info struct for protocols that couldn't care less.
65 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
67 #ifdef HAVE_UNISTD_H
68 #include <unistd.h>
69 #endif
71 #include "blist.h"
72 #include "conversation.h"
73 #include "ft.h"
74 #include "imgstore.h"
75 #include "media.h"
76 #include "notify.h"
77 #include "proxy.h"
78 #include "plugin.h"
79 #include "roomlist.h"
80 #include "status.h"
81 #include "whiteboard.h"
84 /** @copydoc PurpleBuddyIconSpec */
85 struct _PurpleBuddyIconSpec {
86 /** This is a comma-delimited list of image formats or @c NULL if icons
87 * are not supported. Neither the core nor the prpl will actually
88 * check to see if the data it's given matches this; it's entirely up
89 * to the UI to do what it wants
91 char *format;
93 int min_width; /**< Minimum width of this icon */
94 int min_height; /**< Minimum height of this icon */
95 int max_width; /**< Maximum width of this icon */
96 int max_height; /**< Maximum height of this icon */
97 size_t max_filesize; /**< Maximum size in bytes */
98 PurpleIconScaleRules scale_rules; /**< How to stretch this icon */
101 /** Represents an entry containing information that must be supplied by the
102 * user when joining a chat.
104 struct proto_chat_entry {
105 const char *label; /**< User-friendly name of the entry */
106 const char *identifier; /**< Used by the PRPL to identify the option */
107 gboolean required; /**< True if it's required */
108 gboolean is_int; /**< True if the entry expects an integer */
109 int min; /**< Minimum value in case of integer */
110 int max; /**< Maximum value in case of integer */
111 gboolean secret; /**< True if the entry is secret (password) */
114 /** Represents "nudges" and "buzzes" that you may send to a buddy to attract
115 * their attention (or vice-versa).
117 struct _PurpleAttentionType
119 const char *name; /**< Shown in GUI elements */
120 const char *incoming_description; /**< Shown when sent */
121 const char *outgoing_description; /**< Shown when receied */
122 const char *icon_name; /**< Icon to display (optional) */
123 const char *unlocalized_name; /**< Unlocalized name for UIs needing it */
125 /* Reserved fields for future purposes */
126 gpointer _reserved2;
127 gpointer _reserved3;
128 gpointer _reserved4;
132 * Protocol options
134 * These should all be stuff that some plugins can do and others can't.
136 typedef enum
139 * User names are unique to a chat and are not shared between rooms.
141 * XMPP lets you choose what name you want in chats, so it shouldn't
142 * be pulling the aliases from the buddy list for the chat list;
143 * it gets annoying.
145 OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
148 * Chat rooms have topics.
150 * IRC and XMPP support this.
152 OPT_PROTO_CHAT_TOPIC = 0x00000008,
155 * Don't require passwords for sign-in.
157 * Zephyr doesn't require passwords, so there's no
158 * need for a password prompt.
160 OPT_PROTO_NO_PASSWORD = 0x00000010,
163 * Notify on new mail.
165 * MSN and Yahoo notify you when you have new mail.
167 OPT_PROTO_MAIL_CHECK = 0x00000020,
170 * Images in IMs.
172 * Oscar lets you send images in direct IMs.
174 OPT_PROTO_IM_IMAGE = 0x00000040,
177 * Allow passwords to be optional.
179 * Passwords in IRC are optional, and are needed for certain
180 * functionality.
182 OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
185 * Allows font size to be specified in sane point size
187 * Probably just XMPP and Y!M
189 OPT_PROTO_USE_POINTSIZE = 0x00000100,
192 * Set the Register button active even when the username has not
193 * been specified.
195 * Gadu-Gadu doesn't need a username to register new account (because
196 * usernames are assigned by the server).
198 OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
201 * Indicates that slash commands are native to this protocol.
202 * Used as a hint that unknown commands should not be sent as messages.
203 * @since 2.1.0
205 OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400
207 } PurpleProtocolOptions;
210 * A protocol plugin information structure.
212 * Every protocol plugin initializes this structure. It is the gateway
213 * between purple and the protocol plugin. Many of these callbacks can be
214 * NULL. If a callback must be implemented, it has a comment indicating so.
216 struct _PurplePluginProtocolInfo
218 PurpleProtocolOptions options; /**< Protocol options. */
220 GList *user_splits; /**< A GList of PurpleAccountUserSplit */
221 GList *protocol_options; /**< A GList of PurpleAccountOption */
223 PurpleBuddyIconSpec icon_spec; /**< The icon spec. */
226 * Returns the base icon name for the given buddy and account.
227 * If buddy is NULL and the account is non-NULL, it will return the
228 * name to use for the account's icon. If both are NULL, it will
229 * return the name to use for the protocol's icon.
231 * This must be implemented.
233 const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
236 * Fills the four char**'s with string identifiers for "emblems"
237 * that the UI will interpret and display as relevant
239 const char *(*list_emblem)(PurpleBuddy *buddy);
242 * Gets a short string representing this buddy's status. This will
243 * be shown on the buddy list.
245 char *(*status_text)(PurpleBuddy *buddy);
248 * Allows the prpl to add text to a buddy's tooltip.
250 void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
253 * Returns a list of #PurpleStatusType which exist for this account;
254 * this must be implemented, and must add at least the offline and
255 * online states.
257 GList *(*status_types)(PurpleAccount *account);
260 * Returns a list of #PurpleMenuAction structs, which represent extra
261 * actions to be shown in (for example) the right-click menu for @a
262 * node.
264 GList *(*blist_node_menu)(PurpleBlistNode *node);
267 * Returns a list of #proto_chat_entry structs, which represent
268 * information required by the PRPL to join a chat. libpurple will
269 * call join_chat along with the information filled by the user.
271 * @return A list of #proto_chat_entry structs
273 GList *(*chat_info)(PurpleConnection *);
276 * Returns a hashtable which maps #proto_chat_entry struct identifiers
277 * to default options as strings based on chat_name. The resulting
278 * hashtable should be created with g_hash_table_new_full(g_str_hash,
279 * g_str_equal, NULL, g_free);. Use #get_chat_name if you instead need
280 * to extract a chat name from a hashtable.
282 * @param chat_name The chat name to be turned into components
283 * @return Hashtable containing the information extracted from chat_name
285 GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
287 /* All the server-related functions */
289 /** This must be implemented. */
290 void (*login)(PurpleAccount *);
292 /** This must be implemented. */
293 void (*close)(PurpleConnection *);
296 * This PRPL function should return a positive value on success.
297 * If the message is too big to be sent, return -E2BIG. If
298 * the account is not connected, return -ENOTCONN. If the
299 * PRPL is unable to send the message for another reason, return
300 * some other negative value. You can use one of the valid
301 * errno values, or just big something. If the message should
302 * not be echoed to the conversation window, return 0.
304 int (*send_im)(PurpleConnection *, const char *who,
305 const char *message,
306 PurpleMessageFlags flags);
308 void (*set_info)(PurpleConnection *, const char *info);
311 * @return If this protocol requires the PURPLE_TYPING message to
312 * be sent repeatedly to signify that the user is still
313 * typing, then the PRPL should return the number of
314 * seconds to wait before sending a subsequent notification.
315 * Otherwise the PRPL should return 0.
317 unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
320 * Should arrange for purple_notify_userinfo() to be called with
321 * @a who's user info.
323 void (*get_info)(PurpleConnection *, const char *who);
324 void (*set_status)(PurpleAccount *account, PurpleStatus *status);
326 void (*set_idle)(PurpleConnection *, int idletime);
327 void (*change_passwd)(PurpleConnection *, const char *old_pass,
328 const char *new_pass);
330 * Add a buddy to a group on the server.
332 * This PRPL function may be called in situations in which the buddy is
333 * already in the specified group. If the protocol supports
334 * authorization and the user is not already authorized to see the
335 * status of \a buddy, \a add_buddy should request authorization.
337 void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
338 void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
339 void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
340 void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
341 void (*add_permit)(PurpleConnection *, const char *name);
342 void (*add_deny)(PurpleConnection *, const char *name);
343 void (*rem_permit)(PurpleConnection *, const char *name);
344 void (*rem_deny)(PurpleConnection *, const char *name);
345 void (*set_permit_deny)(PurpleConnection *);
348 * Called when the user requests joining a chat. Should arrange for
349 * #serv_got_joined_chat to be called.
351 * @param components A hashtable containing information required to
352 * join the chat as described by the entries returned
353 * by #chat_info. It may also be called when accepting
354 * an invitation, in which case this matches the
355 * data parameter passed to #serv_got_chat_invite.
357 void (*join_chat)(PurpleConnection *, GHashTable *components);
360 * Called when the user refuses a chat invitation.
362 * @param components A hashtable containing information required to
363 * join the chat as passed to #serv_got_chat_invite.
365 void (*reject_chat)(PurpleConnection *, GHashTable *components);
368 * Returns a chat name based on the information in components. Use
369 * #chat_info_defaults if you instead need to generate a hashtable
370 * from a chat name.
372 * @param components A hashtable containing information about the chat.
374 char *(*get_chat_name)(GHashTable *components);
377 * Invite a user to join a chat.
379 * @param id The id of the chat to invite the user to.
380 * @param message A message displayed to the user when the invitation
381 * is received.
382 * @param who The name of the user to send the invation to.
384 void (*chat_invite)(PurpleConnection *, int id,
385 const char *message, const char *who);
387 * Called when the user requests leaving a chat.
389 * @param id The id of the chat to leave
391 void (*chat_leave)(PurpleConnection *, int id);
394 * Send a whisper to a user in a chat.
396 * @param id The id of the chat.
397 * @param who The name of the user to send the whisper to.
398 * @param message The message of the whisper.
400 void (*chat_whisper)(PurpleConnection *, int id,
401 const char *who, const char *message);
404 * Send a message to a chat.
405 * This PRPL function should return a positive value on success.
406 * If the message is too big to be sent, return -E2BIG. If
407 * the account is not connected, return -ENOTCONN. If the
408 * PRPL is unable to send the message for another reason, return
409 * some other negative value. You can use one of the valid
410 * errno values, or just big something. If the message should
411 * not be echoed to the conversation window, return 0.
413 * @param id The id of the chat to send the message to.
414 * @param message The message to send to the chat.
415 * @param flags A bitwise OR of #PurpleMessageFlags representing
416 * message flags.
417 * @return A positive number or 0 in case of succes,
418 * a negative error number in case of failure.
420 int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
422 /** If implemented, this will be called regularly for this prpl's
423 * active connections. You'd want to do this if you need to repeatedly
424 * send some kind of keepalive packet to the server to avoid being
425 * disconnected. ("Regularly" is defined by
426 * <code>KEEPALIVE_INTERVAL</code> in <tt>libpurple/connection.c</tt>.)
428 void (*keepalive)(PurpleConnection *);
430 /** new user registration */
431 void (*register_user)(PurpleAccount *);
434 * @deprecated Use #PurplePluginProtocolInfo.get_info instead.
436 void (*get_cb_info)(PurpleConnection *, int, const char *who);
438 * @deprecated Use #PurplePluginProtocolInfo.get_cb_real_name and
439 * #PurplePluginProtocolInfo.status_text instead.
441 void (*get_cb_away)(PurpleConnection *, int, const char *who);
443 /** save/store buddy's alias on server list/roster */
444 void (*alias_buddy)(PurpleConnection *, const char *who,
445 const char *alias);
447 /** change a buddy's group on a server list/roster */
448 void (*group_buddy)(PurpleConnection *, const char *who,
449 const char *old_group, const char *new_group);
451 /** rename a group on a server list/roster */
452 void (*rename_group)(PurpleConnection *, const char *old_name,
453 PurpleGroup *group, GList *moved_buddies);
455 void (*buddy_free)(PurpleBuddy *);
457 void (*convo_closed)(PurpleConnection *, const char *who);
460 * Convert the username @a who to its canonical form. (For example,
461 * AIM treats "fOo BaR" and "foobar" as the same user; this function
462 * should return the same normalized string for both of those.)
464 const char *(*normalize)(const PurpleAccount *, const char *who);
467 * Set the buddy icon for the given connection to @a img. The prpl
468 * does NOT own a reference to @a img; if it needs one, it must
469 * #purple_imgstore_ref(@a img) itself.
471 void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
473 void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
475 /** Gets the real name of a participant in a chat. For example, on
476 * XMPP this turns a chat room nick <tt>foo</tt> into
477 * <tt>room\@server/foo</tt>
478 * @param gc the connection on which the room is.
479 * @param id the ID of the chat room.
480 * @param who the nickname of the chat participant.
481 * @return the real name of the participant. This string must be
482 * freed by the caller.
484 char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
486 void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
488 PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
490 /* room listing prpl callbacks */
491 PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
492 void (*roomlist_cancel)(PurpleRoomlist *list);
493 void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
495 /* file transfer callbacks */
496 gboolean (*can_receive_file)(PurpleConnection *, const char *who);
497 void (*send_file)(PurpleConnection *, const char *who, const char *filename);
498 PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
500 /** Checks whether offline messages to @a buddy are supported.
501 * @return @c TRUE if @a buddy can be sent messages while they are
502 * offline, or @c FALSE if not.
504 gboolean (*offline_message)(const PurpleBuddy *buddy);
506 PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
508 /** For use in plugins that may understand the underlying protocol */
509 int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
511 /* room list serialize */
512 char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
514 /** Remove the user from the server. The account can either be
515 * connected or disconnected. After the removal is finished, the
516 * connection will stay open and has to be closed!
518 /* This is here rather than next to register_user for API compatibility
519 * reasons.
521 void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
523 /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
524 gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
525 GList *(*get_attention_types)(PurpleAccount *acct);
528 * The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
529 * This allows adding more functions to this struct without requiring a major version bump.
531 unsigned long struct_size;
533 /* NOTE:
534 * If more functions are added, they should accessed using the following syntax:
536 * if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
537 * prpl->new_function(...);
539 * instead of
541 * if (prpl->new_function != NULL)
542 * prpl->new_function(...);
544 * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
545 * functions (e.g. login, send_im etc.) too.
548 /** This allows protocols to specify additional strings to be used for
549 * various purposes. The idea is to stuff a bunch of strings in this hash
550 * table instead of expanding the struct for every addition. This hash
551 * table is allocated every call and MUST be unrefed by the caller.
553 * @param account The account to specify. This can be NULL.
554 * @return The protocol's string hash table. The hash table should be
555 * destroyed by the caller when it's no longer needed.
557 GHashTable *(*get_account_text_table)(PurpleAccount *account);
560 * Initiate a media session with the given contact.
562 * @param account The account to initiate the media session on.
563 * @param who The remote user to initiate the session with.
564 * @param type The type of media session to initiate.
565 * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
567 gboolean (*initiate_media)(PurpleAccount *account, const char *who,
568 PurpleMediaSessionType type);
571 * Checks to see if the given contact supports the given type of media session.
573 * @param account The account the contact is on.
574 * @param who The remote user to check for media capability with.
575 * @return The media caps the contact supports.
577 PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
578 const char *who);
581 * Returns an array of "PurpleMood"s, with the last one having
582 * "mood" set to @c NULL.
583 * @since 2.7.0
585 PurpleMood *(*get_moods)(PurpleAccount *account);
588 * Set the user's "friendly name" (or alias or nickname or
589 * whatever term you want to call it) on the server. The
590 * protocol plugin should call success_cb or failure_cb
591 * *asynchronously* (if it knows immediately that the set will fail,
592 * call one of the callbacks from an idle/0-second timeout) depending
593 * on if the nickname is set successfully.
595 * @param gc The connection for which to set an alias
596 * @param alias The new server-side alias/nickname for this account,
597 * or NULL to unset the alias/nickname (or return it to
598 * a protocol-specific "default").
599 * @param success_cb Callback to be called if the public alias is set
600 * @param failure_cb Callback to be called if setting the public alias
601 * fails
602 * @see purple_account_set_public_alias
603 * @since 2.7.0
605 void (*set_public_alias)(PurpleConnection *gc, const char *alias,
606 PurpleSetPublicAliasSuccessCallback success_cb,
607 PurpleSetPublicAliasFailureCallback failure_cb);
609 * Retrieve the user's "friendly name" as set on the server.
610 * The protocol plugin should call success_cb or failure_cb
611 * *asynchronously* (even if it knows immediately that the get will fail,
612 * call one of the callbacks from an idle/0-second timeout) depending
613 * on if the nickname is retrieved.
615 * @param gc The connection for which to retireve the alias
616 * @param success_cb Callback to be called with the retrieved alias
617 * @param failure_cb Callback to be called if the prpl is unable to
618 * retrieve the alias
619 * @see purple_account_get_public_alias
620 * @since 2.7.0
622 void (*get_public_alias)(PurpleConnection *gc,
623 PurpleGetPublicAliasSuccessCallback success_cb,
624 PurpleGetPublicAliasFailureCallback failure_cb);
627 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
628 (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
629 || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
630 prpl->member != NULL)
633 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
634 ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
636 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
637 ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
639 #ifdef __cplusplus
640 extern "C" {
641 #endif
643 /**************************************************************************/
644 /** @name Attention Type API */
645 /**************************************************************************/
646 /*@{*/
649 * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
651 * @param ulname A non-localized string that can be used by UIs in need of such
652 * non-localized strings. This should be the same as @a name,
653 * without localization.
654 * @param name A localized string that the UI may display for the event. This
655 * should be the same string as @a ulname, with localization.
656 * @param inc_desc A localized description shown when the event is received.
657 * @param out_desc A localized description shown when the event is sent.
658 * @return A pointer to the new object.
659 * @since 2.4.0
661 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
662 const char *inc_desc, const char *out_desc);
665 * Sets the displayed name of the attention-demanding event.
667 * @param type The attention type.
668 * @param name The localized name that will be displayed by UIs. This should be
669 * the same string given as the unlocalized name, but with
670 * localization.
671 * @since 2.4.0
673 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
676 * Sets the description of the attention-demanding event shown in conversations
677 * when the event is received.
679 * @param type The attention type.
680 * @param desc The localized description for incoming events.
681 * @since 2.4.0
683 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
686 * Sets the description of the attention-demanding event shown in conversations
687 * when the event is sent.
689 * @param type The attention type.
690 * @param desc The localized description for outgoing events.
691 * @since 2.4.0
693 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
696 * Sets the name of the icon to display for the attention event; this is optional.
698 * @param type The attention type.
699 * @param name The icon's name.
700 * @note Icons are optional for attention events.
701 * @since 2.4.0
703 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
706 * Sets the unlocalized name of the attention event; some UIs may need this,
707 * thus it is required.
709 * @param type The attention type.
710 * @param ulname The unlocalized name. This should be the same string given as
711 * the localized name, but without localization.
712 * @since 2.4.0
714 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
717 * Get the attention type's name as displayed by the UI.
719 * @param type The attention type.
720 * @return The name.
721 * @since 2.4.0
723 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
726 * Get the attention type's description shown when the event is received.
728 * @param type The attention type.
729 * @return The description.
730 * @since 2.4.0
732 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
735 * Get the attention type's description shown when the event is sent.
737 * @param type The attention type.
738 * @return The description.
739 * @since 2.4.0
741 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
744 * Get the attention type's icon name.
746 * @param type The attention type.
747 * @return The icon name or @c NULL if unset/empty.
748 * @note Icons are optional for attention events.
749 * @since 2.4.0
751 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
754 * Get the attention type's unlocalized name; this is useful for some UIs.
756 * @param type The attention type
757 * @return The unlocalized name.
758 * @since 2.4.0
760 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
762 /*@}*/
764 /**************************************************************************/
765 /** @name Protocol Plugin API */
766 /**************************************************************************/
767 /*@{*/
770 * Notifies Purple that our account's idle state and time have changed.
772 * This is meant to be called from protocol plugins.
774 * @param account The account.
775 * @param idle The user's idle state.
776 * @param idle_time The user's idle time.
778 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
779 time_t idle_time);
782 * Notifies Purple of our account's log-in time.
784 * This is meant to be called from protocol plugins.
786 * @param account The account the user is on.
787 * @param login_time The user's log-in time.
789 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
792 * Notifies Purple that our account's status has changed.
794 * This is meant to be called from protocol plugins.
796 * @param account The account the user is on.
797 * @param status_id The status ID.
798 * @param ... A NULL-terminated list of attribute IDs and values,
799 * beginning with the value for @a attr_id.
801 void purple_prpl_got_account_status(PurpleAccount *account,
802 const char *status_id, ...) G_GNUC_NULL_TERMINATED;
805 * Notifies Purple that our account's actions have changed. This is only
806 * called after the initial connection. Emits the account-actions-changed
807 * signal.
809 * This is meant to be called from protocol plugins.
811 * @param account The account.
813 * @see account-actions-changed
814 * @since 2.6.0
816 void purple_prpl_got_account_actions(PurpleAccount *account);
819 * Notifies Purple that a buddy's idle state and time have changed.
821 * This is meant to be called from protocol plugins.
823 * @param account The account the user is on.
824 * @param name The name of the buddy.
825 * @param idle The user's idle state.
826 * @param idle_time The user's idle time. This is the time at
827 * which the user became idle, in seconds since
828 * the epoch. If the PRPL does not know this value
829 * then it should pass 0.
831 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
832 gboolean idle, time_t idle_time);
835 * Notifies Purple of a buddy's log-in time.
837 * This is meant to be called from protocol plugins.
839 * @param account The account the user is on.
840 * @param name The name of the buddy.
841 * @param login_time The user's log-in time.
843 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
844 time_t login_time);
847 * Notifies Purple that a buddy's status has been activated.
849 * This is meant to be called from protocol plugins.
851 * @param account The account the user is on.
852 * @param name The name of the buddy.
853 * @param status_id The status ID.
854 * @param ... A NULL-terminated list of attribute IDs and values,
855 * beginning with the value for @a attr_id.
857 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
858 const char *status_id, ...) G_GNUC_NULL_TERMINATED;
861 * Notifies libpurple that a buddy's status has been deactivated
863 * This is meant to be called from protocol plugins.
865 * @param account The account the user is on.
866 * @param name The name of the buddy.
867 * @param status_id The status ID.
869 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
870 const char *status_id);
873 * Informs the server that our account's status changed.
875 * @param account The account the user is on.
876 * @param old_status The previous status.
877 * @param new_status The status that was activated, or deactivated
878 * (in the case of independent statuses).
880 void purple_prpl_change_account_status(PurpleAccount *account,
881 PurpleStatus *old_status,
882 PurpleStatus *new_status);
885 * Retrieves the list of stock status types from a prpl.
887 * @param account The account the user is on.
888 * @param presence The presence for which we're going to get statuses
890 * @return List of statuses
892 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
895 * Send an attention request message.
897 * @param gc The connection to send the message on.
898 * @param who Whose attention to request.
899 * @param type_code An index into the prpl's attention_types list determining the type
900 * of the attention request command to send. 0 if prpl only defines one
901 * (for example, Yahoo and MSN), but some protocols define more (MySpaceIM).
903 * Note that you can't send arbitrary PurpleAttentionType's, because there is
904 * only a fixed set of attention commands.
906 * @since 2.5.0
908 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
911 * Process an incoming attention message.
913 * @param gc The connection that received the attention message.
914 * @param who Who requested your attention.
915 * @param type_code An index into the prpl's attention_types list determining the type
916 * of the attention request command to send.
918 * @since 2.5.0
920 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
923 * Process an incoming attention message in a chat.
925 * @param gc The connection that received the attention message.
926 * @param id The chat id.
927 * @param who Who requested your attention.
928 * @param type_code An index into the prpl's attention_types list determining the type
929 * of the attention request command to send.
931 * @since 2.5.0
933 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
936 * Determines if the contact supports the given media session type.
938 * @param account The account the user is on.
939 * @param who The name of the contact to check capabilities for.
941 * @return The media caps the contact supports.
943 PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
944 const char *who);
947 * Initiates a media session with the given contact.
949 * @param account The account the user is on.
950 * @param who The name of the contact to start a session with.
951 * @param type The type of media session to start.
953 * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
955 gboolean purple_prpl_initiate_media(PurpleAccount *account,
956 const char *who,
957 PurpleMediaSessionType type);
960 * Signals that the prpl received capabilities for the given contact.
962 * This function is intended to be used only by prpls.
964 * @param account The account the user is on.
965 * @param who The name of the contact for which capabilities have been received.
966 * @since 2.7.0
968 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
970 /*@}*/
972 /**************************************************************************/
973 /** @name Protocol Plugin Subsystem API */
974 /**************************************************************************/
975 /*@{*/
978 * Finds a protocol plugin structure of the specified type.
980 * @param id The protocol plugin;
982 PurplePlugin *purple_find_prpl(const char *id);
984 /*@}*/
986 #ifdef __cplusplus
988 #endif
990 #endif /* _PRPL_H_ */