libpurple/protocol.h@637155f87448
libpurple/protocol.h
Fri, 30 Aug 2013 00:58:55 +0530
- author
- Ankit Vani <a@nevitus.org>
- date
- Fri, 30 Aug 2013 00:58:55 +0530
- branch
- soc.2013.gobjectification.plugins
- changeset 36609
- 637155f87448
- parent 36608
- bb8dbeba5bed
- child 36610
- 3d99b9c0bf90
- permissions
- -rw-r--r--
Refactored the protocols to use purple_buddy_icon_spec_new()
/** * @file protocol.h PurpleProtocol and PurpleProtocolInterface API * @ingroup core */ /* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this * source distribution. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA */ #ifndef _PURPLE_PROTOCOL_H_ #define _PURPLE_PROTOCOL_H_ #define PURPLE_TYPE_PROTOCOL (purple_protocol_get_type()) #define PURPLE_PROTOCOL(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocol)) #define PURPLE_PROTOCOL_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_PROTOCOL, PurpleProtocolClass)) #define PURPLE_IS_PROTOCOL(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL)) #define PURPLE_IS_PROTOCOL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_PROTOCOL)) #define PURPLE_PROTOCOL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocolClass)) #define PURPLE_PROTOCOL_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocolInterface)) /** @copydoc _PurpleProtocol */ typedef struct _PurpleProtocol PurpleProtocol; /** @copydoc _PurpleProtocolClass */ typedef struct _PurpleProtocolClass PurpleProtocolClass; /** @copydoc _PurpleProtocolInterface */ typedef struct _PurpleProtocolInterface PurpleProtocolInterface; #include "account.h" #include "accountopt.h" #include "buddylist.h" #include "connection.h" #include "conversations.h" #include "ft.h" #include "imgstore.h" #include "media.h" #include "roomlist.h" #include "status.h" #include "whiteboard.h" /** * Represents an instance of a protocol registered with the protocols * subsystem. */ struct _PurpleProtocol { /*< private >*/ GObject gparent; }; /** * The base class for all protocols. * * Protocols must set the members of this class to appropriate values upon * class initialization. */ struct _PurpleProtocolClass { /*< private >*/ GObjectClass parent_class; const char *id; /**< Protocol ID */ const char *name; /**< Translated name of the protocol */ PurpleProtocolOptions options; /**< Protocol options */ GList *user_splits; /**< A GList of PurpleAccountUserSplit */ GList *protocol_options; /**< A GList of PurpleAccountOption */ PurpleBuddyIconSpec *icon_spec; /**< The icon spec. */ PurpleWhiteboardPrplOps *whiteboard_protocol_ops; void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); }; /** * The protocol interface. * * Every protocol implements this interface. It is the gateway between purple * and the protocol's functions. Many of these callbacks can be NULL. If a * callback must be implemented, it has a comment indicating so. */ struct _PurpleProtocolInterface { /*< private >*/ GTypeInterface parent_iface; /** * Returns the actions the protocol can perform. These will show up in the * Accounts menu, under a submenu with the name of the account. */ GList *(*get_actions)(PurpleConnection *); /** * Returns the base icon name for the given buddy and account. * If buddy is NULL and the account is non-NULL, it will return the * name to use for the account's icon. If both are NULL, it will * return the name to use for the protocol's icon. * * This must be implemented. */ const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy); /** * Fills the four char**'s with string identifiers for "emblems" * that the UI will interpret and display as relevant */ const char *(*list_emblem)(PurpleBuddy *buddy); /** * Gets a short string representing this buddy's status. This will * be shown on the buddy list. */ char *(*status_text)(PurpleBuddy *buddy); /** * Allows the protocol to add text to a buddy's tooltip. */ void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full); /** * Returns a list of #PurpleStatusType which exist for this account; * this must be implemented, and must add at least the offline and * online states. */ GList *(*status_types)(PurpleAccount *account); /** * Returns a list of #PurpleMenuAction structs, which represent extra * actions to be shown in (for example) the right-click menu for @a * node. */ GList *(*blist_node_menu)(PurpleBlistNode *node); /** * Returns a list of #PurpleProtocolChatEntry structs, which represent * information required by the protocol to join a chat. libpurple will * call join_chat along with the information filled by the user. * * @return A list of #PurpleProtocolChatEntry structs */ GList *(*chat_info)(PurpleConnection *); /** * Returns a hashtable which maps #PurpleProtocolChatEntry struct * identifiers to default options as strings based on chat_name. The * resulting hashtable should be created with * g_hash_table_new_full(g_str_hash, g_str_equal, NULL, g_free);. Use * #get_chat_name if you instead need to extract a chat name from a * hashtable. * * @param chat_name The chat name to be turned into components * @return Hashtable containing the information extracted from chat_name */ GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name); /* All the server-related functions */ /** This must be implemented. */ void (*login)(PurpleAccount *); /** This must be implemented. */ void (*close)(PurpleConnection *); /** * This protocol function should return a positive value on success. * If the message is too big to be sent, return -E2BIG. If * the account is not connected, return -ENOTCONN. If the * protocol is unable to send the message for another reason, return * some other negative value. You can use one of the valid * errno values, or just big something. If the message should * not be echoed to the conversation window, return 0. */ int (*send_im)(PurpleConnection *, const char *who, const char *message, PurpleMessageFlags flags); void (*set_info)(PurpleConnection *, const char *info); /** * @return If this protocol requires the PURPLE_IM_TYPING message to * be sent repeatedly to signify that the user is still * typing, then the protocol should return the number of * seconds to wait before sending a subsequent notification. * Otherwise the protocol should return 0. */ unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleIMTypingState state); /** * Should arrange for purple_notify_userinfo() to be called with * @a who's user info. */ void (*get_info)(PurpleConnection *, const char *who); void (*set_status)(PurpleAccount *account, PurpleStatus *status); void (*set_idle)(PurpleConnection *, int idletime); void (*change_passwd)(PurpleConnection *, const char *old_pass, const char *new_pass); /** * Add a buddy to a group on the server. * * This protocol function may be called in situations in which the buddy is * already in the specified group. If the protocol supports * authorization and the user is not already authorized to see the * status of \a buddy, \a add_buddy should request authorization. * * If authorization is required, then use the supplied invite message. */ void (*add_buddy)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message); void (*add_buddies)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message); void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group); void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups); void (*add_permit)(PurpleConnection *, const char *name); void (*add_deny)(PurpleConnection *, const char *name); void (*rem_permit)(PurpleConnection *, const char *name); void (*rem_deny)(PurpleConnection *, const char *name); void (*set_permit_deny)(PurpleConnection *); /** * Called when the user requests joining a chat. Should arrange for * #serv_got_joined_chat to be called. * * @param components A hashtable containing information required to * join the chat as described by the entries returned * by #chat_info. It may also be called when accepting * an invitation, in which case this matches the * data parameter passed to #serv_got_chat_invite. */ void (*join_chat)(PurpleConnection *, GHashTable *components); /** * Called when the user refuses a chat invitation. * * @param components A hashtable containing information required to * join the chat as passed to #serv_got_chat_invite. */ void (*reject_chat)(PurpleConnection *, GHashTable *components); /** * Returns a chat name based on the information in components. Use * #chat_info_defaults if you instead need to generate a hashtable * from a chat name. * * @param components A hashtable containing information about the chat. */ char *(*get_chat_name)(GHashTable *components); /** * Invite a user to join a chat. * * @param id The id of the chat to invite the user to. * @param message A message displayed to the user when the invitation * is received. * @param who The name of the user to send the invation to. */ void (*chat_invite)(PurpleConnection *, int id, const char *message, const char *who); /** * Called when the user requests leaving a chat. * * @param id The id of the chat to leave */ void (*chat_leave)(PurpleConnection *, int id); /** * Send a whisper to a user in a chat. * * @param id The id of the chat. * @param who The name of the user to send the whisper to. * @param message The message of the whisper. */ void (*chat_whisper)(PurpleConnection *, int id, const char *who, const char *message); /** * Send a message to a chat. * This protocol function should return a positive value on success. * If the message is too big to be sent, return -E2BIG. If * the account is not connected, return -ENOTCONN. If the * protocol is unable to send the message for another reason, return * some other negative value. You can use one of the valid * errno values, or just big something. * * @param id The id of the chat to send the message to. * @param message The message to send to the chat. * @param flags A bitwise OR of #PurpleMessageFlags representing * message flags. * @return A positive number or 0 in case of success, * a negative error number in case of failure. */ int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags); /** If implemented, this will be called regularly for this protocol's * active connections. You'd want to do this if you need to repeatedly * send some kind of keepalive packet to the server to avoid being * disconnected. ("Regularly" is defined by * <code>KEEPALIVE_INTERVAL</code> in <tt>libpurple/connection.c</tt>.) */ void (*keepalive)(PurpleConnection *); /** new user registration */ void (*register_user)(PurpleAccount *); /** Remove the user from the server. The account can either be * connected or disconnected. After the removal is finished, the * connection will stay open and has to be closed! */ void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data); /** * @deprecated Use #PurpleProtocol.get_info instead. */ void (*get_cb_info)(PurpleConnection *, int, const char *who); /** save/store buddy's alias on server list/roster */ void (*alias_buddy)(PurpleConnection *, const char *who, const char *alias); /** change a buddy's group on a server list/roster */ void (*group_buddy)(PurpleConnection *, const char *who, const char *old_group, const char *new_group); /** rename a group on a server list/roster */ void (*rename_group)(PurpleConnection *, const char *old_name, PurpleGroup *group, GList *moved_buddies); void (*buddy_free)(PurpleBuddy *); void (*convo_closed)(PurpleConnection *, const char *who); /** * Convert the username @a who to its canonical form. Also checks for * validity. * * For example, AIM treats "fOo BaR" and "foobar" as the same user; this * function should return the same normalized string for both of those. * On the other hand, both of these are invalid for protocols with * number-based usernames, so function should return NULL in such case. * * @param account The account the username is related to. Can * be NULL. * @param who The username to convert. * @return Normalized username, or NULL, if it's invalid. */ const char *(*normalize)(const PurpleAccount *account, const char *who); /** * Set the buddy icon for the given connection to @a img. The protocol * does NOT own a reference to @a img; if it needs one, it must * #purple_imgstore_ref(@a img) itself. */ void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img); void (*remove_group)(PurpleConnection *gc, PurpleGroup *group); /** Gets the real name of a participant in a chat. For example, on * XMPP this turns a chat room nick <tt>foo</tt> into * <tt>room\@server/foo</tt> * @param gc the connection on which the room is. * @param id the ID of the chat room. * @param who the nickname of the chat participant. * @return the real name of the participant. This string must be * freed by the caller. */ char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who); void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic); PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name); /* room listing protocol callbacks */ PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc); void (*roomlist_cancel)(PurpleRoomlist *list); void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category); /* file transfer callbacks */ gboolean (*can_receive_file)(PurpleConnection *, const char *who); void (*send_file)(PurpleConnection *, const char *who, const char *filename); PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who); /** Checks whether offline messages to @a buddy are supported. * @return @c TRUE if @a buddy can be sent messages while they are * offline, or @c FALSE if not. */ gboolean (*offline_message)(const PurpleBuddy *buddy); PurpleWhiteboardPrplOps *whiteboard_protocol_ops; /** For use in plugins that may understand the underlying protocol */ int (*send_raw)(PurpleConnection *gc, const char *buf, int len); /* room list serialize */ char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room); /* Attention API for sending & receiving zaps/nudges/buzzes etc. */ gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type); GList *(*get_attention_types)(PurpleAccount *acct); /** This allows protocols to specify additional strings to be used for * various purposes. The idea is to stuff a bunch of strings in this hash * table instead of expanding the struct for every addition. This hash * table is allocated every call and MUST be unrefed by the caller. * * @param account The account to specify. This can be NULL. * @return The protocol's string hash table. The hash table should be * destroyed by the caller when it's no longer needed. */ GHashTable *(*get_account_text_table)(PurpleAccount *account); /** * Initiate a media session with the given contact. * * @param account The account to initiate the media session on. * @param who The remote user to initiate the session with. * @param type The type of media session to initiate. * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media * session or stream will be successfully created) */ gboolean (*initiate_media)(PurpleAccount *account, const char *who, PurpleMediaSessionType type); /** * Checks to see if the given contact supports the given type of media * session. * * @param account The account the contact is on. * @param who The remote user to check for media capability with. * @return The media caps the contact supports. */ PurpleMediaCaps (*get_media_caps)(PurpleAccount *account, const char *who); /** * Returns an array of "PurpleMood"s, with the last one having * "mood" set to @c NULL. */ PurpleMood *(*get_moods)(PurpleAccount *account); /** * Set the user's "friendly name" (or alias or nickname or * whatever term you want to call it) on the server. The * protocol should call success_cb or failure_cb * *asynchronously* (if it knows immediately that the set will fail, * call one of the callbacks from an idle/0-second timeout) depending * on if the nickname is set successfully. * * @param gc The connection for which to set an alias * @param alias The new server-side alias/nickname for this account, * or NULL to unset the alias/nickname (or return it to * a protocol-specific "default"). * @param success_cb Callback to be called if the public alias is set * @param failure_cb Callback to be called if setting the public alias * fails * @see purple_account_set_public_alias */ void (*set_public_alias)(PurpleConnection *gc, const char *alias, PurpleSetPublicAliasSuccessCallback success_cb, PurpleSetPublicAliasFailureCallback failure_cb); /** * Retrieve the user's "friendly name" as set on the server. * The protocol should call success_cb or failure_cb * *asynchronously* (even if it knows immediately that the get will fail, * call one of the callbacks from an idle/0-second timeout) depending * on if the nickname is retrieved. * * @param gc The connection for which to retireve the alias * @param success_cb Callback to be called with the retrieved alias * @param failure_cb Callback to be called if the protocol is unable to * retrieve the alias * @see purple_account_get_public_alias */ void (*get_public_alias)(PurpleConnection *gc, PurpleGetPublicAliasSuccessCallback success_cb, PurpleGetPublicAliasFailureCallback failure_cb); /** * Gets the maximum message size in bytes for the protocol. It may * depend on connection-specific variables (like protocol version). * * This value is intended for plaintext message, the exact value may be * lower because of: * - used newlines (some protocols count them as more than one byte), * - formatting, * - used special characters. * * @param gc The connection to query, or NULL to get safe minimum. * @return Maximum message size, or 0 if unspecified or infinite. */ gsize (*get_max_message_size)(PurpleConnection *gc); }; /** * Defines a protocol type using the CamelCase type name of the protocol and * the function prefix for the *_get_type(), *_base_init(), *_base_finalize() * and *_interface_init() functions of the protocol. */ #define PURPLE_PROTOCOL_DEFINE(TypeName, func_prefix) \ PURPLE_PROTOCOL_DEFINE_EXTENDED(TypeName, func_prefix, \ PURPLE_TYPE_PROTOCOL, 0) /** TODO register type dynamically (or statically if configured so) * Defines a protocol type using the CamelCase type name of the protocol, the * function prefix for the *_get_type(), *_base_init(), *_base_finalize() and * *_interface_init() functions, the base type, and the type flags. */ #define PURPLE_PROTOCOL_DEFINE_EXTENDED(TypeName, func_prefix, BaseType, TypeFlags) \ GType func_prefix##_get_type(void) { \ static GType type = 0; \ if (type == 0) { \ static const GTypeInfo info = { \ .instance_size = sizeof(TypeName), \ .class_size = sizeof(TypeName##Class), \ .base_init = (GBaseInitFunc)func_prefix##_base_init, \ .base_finalize = (GBaseFinalizeFunc)func_prefix##_base_finalize, \ }; \ static const GInterfaceInfo iface_info = { \ .interface_init = (GInterfaceInitFunc)func_prefix##_interface_init, \ }; \ type = g_type_register_static(BaseType, #TypeName, \ &info, TypeFlags); \ g_type_add_interface_static(type, PURPLE_TYPE_PROTOCOL, &iface_info); \ } \ return type; \ } G_BEGIN_DECLS /**************************************************************************/ /** @name Protocol API */ /**************************************************************************/ /*@{*/ /** TODO * Returns the GType for #PurpleProtocol. */ GType purple_protocol_get_type(void); /** TODO * Returns the ID of a protocol. * * @param protocol The protocol. * * @return The ID of the protocol. */ const char *purple_protocol_get_id(const PurpleProtocol *protocol); /** TODO * Returns the translated name of a protocol. * * @param protocol The protocol. * * @return The translated name of the protocol. */ const char *purple_protocol_get_name(const PurpleProtocol *protocol); /** TODO * Returns the options of a protocol. * * @param protocol The protocol. * * @return The options of the protocol. */ PurpleProtocolOptions purple_protocol_get_options(const PurpleProtocol *protocol); /** TODO * Returns the user splits of a protocol. * * @param protocol The protocol. * * @return The user splits of the protocol. */ GList *purple_protocol_get_user_splits(const PurpleProtocol *protocol); /** TODO * Returns the protocol options of a protocol. * * @param protocol The protocol. * * @return The protocol options of the protocol. */ GList *purple_protocol_get_protocol_options(const PurpleProtocol *protocol); /** TODO * Returns the icon spec of a protocol. * * @param protocol The protocol. * * @return The icon spec of the protocol. */ PurpleBuddyIconSpec *purple_protocol_get_icon_spec(const PurpleProtocol *protocol); /** TODO * Returns the whiteboard ops of a protocol. * * @param protocol The protocol. * * @return The whiteboard ops of the protocol. */ PurpleWhiteboardPrplOps *purple_protocol_get_whiteboard_ops(const PurpleProtocol *protocol); /** * Notifies Purple that our account's idle state and time have changed. * * This is meant to be called from protocols. * * @param account The account. * @param idle The user's idle state. * @param idle_time The user's idle time. */ void purple_protocol_got_account_idle(PurpleAccount *account, gboolean idle, time_t idle_time); /** * Notifies Purple of our account's log-in time. * * This is meant to be called from protocols. * * @param account The account the user is on. * @param login_time The user's log-in time. */ void purple_protocol_got_account_login_time(PurpleAccount *account, time_t login_time); /** * Notifies Purple that our account's status has changed. * * This is meant to be called from protocols. * * @param account The account the user is on. * @param status_id The status ID. * @param ... A NULL-terminated list of attribute IDs and values, * beginning with the value for @a attr_id. */ void purple_protocol_got_account_status(PurpleAccount *account, const char *status_id, ...) G_GNUC_NULL_TERMINATED; /** * Notifies Purple that our account's actions have changed. This is only * called after the initial connection. Emits the account-actions-changed * signal. * * This is meant to be called from protocols. * * @param account The account. * * @see account-actions-changed */ void purple_protocol_got_account_actions(PurpleAccount *account); /** * Notifies Purple that a buddy's idle state and time have changed. * * This is meant to be called from protocols. * * @param account The account the user is on. * @param name The name of the buddy. * @param idle The user's idle state. * @param idle_time The user's idle time. This is the time at * which the user became idle, in seconds since * the epoch. If the protocol does not know this value * then it should pass 0. */ void purple_protocol_got_user_idle(PurpleAccount *account, const char *name, gboolean idle, time_t idle_time); /** * Notifies Purple of a buddy's log-in time. * * This is meant to be called from protocols. * * @param account The account the user is on. * @param name The name of the buddy. * @param login_time The user's log-in time. */ void purple_protocol_got_user_login_time(PurpleAccount *account, const char *name, time_t login_time); /** * Notifies Purple that a buddy's status has been activated. * * This is meant to be called from protocols. * * @param account The account the user is on. * @param name The name of the buddy. * @param status_id The status ID. * @param ... A NULL-terminated list of attribute IDs and values, * beginning with the value for @a attr_id. */ void purple_protocol_got_user_status(PurpleAccount *account, const char *name, const char *status_id, ...) G_GNUC_NULL_TERMINATED; /** * Notifies libpurple that a buddy's status has been deactivated * * This is meant to be called from protocols. * * @param account The account the user is on. * @param name The name of the buddy. * @param status_id The status ID. */ void purple_protocol_got_user_status_deactive(PurpleAccount *account, const char *name, const char *status_id); /** * Informs the server that our account's status changed. * * @param account The account the user is on. * @param old_status The previous status. * @param new_status The status that was activated, or deactivated * (in the case of independent statuses). */ void purple_protocol_change_account_status(PurpleAccount *account, PurpleStatus *old_status, PurpleStatus *new_status); /** * Retrieves the list of stock status types from a protocol. * * @param account The account the user is on. * @param presence The presence for which we're going to get statuses * * @return List of statuses */ GList *purple_protocol_get_statuses(PurpleAccount *account, PurplePresence *presence); /** * Send an attention request message. * * @param gc The connection to send the message on. * @param who Whose attention to request. * @param type_code An index into the protocol's attention_types list * determining the type of the attention request command to * send. 0 if protocol only defines one (for example, Yahoo and * MSN), but some protocols define more (MySpaceIM). * * Note that you can't send arbitrary PurpleAttentionType's, because there is * only a fixed set of attention commands. */ void purple_protocol_send_attention(PurpleConnection *gc, const char *who, guint type_code); /** * Process an incoming attention message. * * @param gc The connection that received the attention message. * @param who Who requested your attention. * @param type_code An index into the protocol's attention_types list * determining the type of the attention request command to * send. */ void purple_protocol_got_attention(PurpleConnection *gc, const char *who, guint type_code); /** * Process an incoming attention message in a chat. * * @param gc The connection that received the attention message. * @param id The chat id. * @param who Who requested your attention. * @param type_code An index into the protocol's attention_types list * determining the type of the attention request command to * send. */ void purple_protocol_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code); /** * Determines if the contact supports the given media session type. * * @param account The account the user is on. * @param who The name of the contact to check capabilities for. * * @return The media caps the contact supports. */ PurpleMediaCaps purple_protocol_get_media_caps(PurpleAccount *account, const char *who); /** * Initiates a media session with the given contact. * * @param account The account the user is on. * @param who The name of the contact to start a session with. * @param type The type of media session to start. * * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media * session or stream will be successfully created) */ gboolean purple_protocol_initiate_media(PurpleAccount *account, const char *who, PurpleMediaSessionType type); /** * Signals that the protocol received capabilities for the given contact. * * This function is intended to be used only by protocols. * * @param account The account the user is on. * @param who The name of the contact for which capabilities have been received. */ void purple_protocol_got_media_caps(PurpleAccount *account, const char *who); /*@}*/ /* TODO */ /**************************************************************************/ /** @name Protocol Interface API */ /**************************************************************************/ /*@{*/ /** @copydoc _PurpleProtocolInterface::get_actions */ GList *purple_protocol_iface_get_actions(PurpleProtocol *, PurpleConnection *); /** @copydoc _PurpleProtocolInterface::list_icon */ const char *purple_protocol_iface_list_icon(PurpleProtocol *, PurpleAccount *account, PurpleBuddy *buddy); /** @copydoc _PurpleProtocolInterface::list_emblem */ const char *purple_protocol_iface_list_emblem(PurpleProtocol *, PurpleBuddy *buddy); /** @copydoc _PurpleProtocolInterface::status_text */ char *purple_protocol_iface_status_text(PurpleProtocol *, PurpleBuddy *buddy); /** @copydoc _PurpleProtocolInterface::tooltip_text */ void purple_protocol_iface_tooltip_text(PurpleProtocol *, PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full); /** @copydoc _PurpleProtocolInterface::status_types */ GList *purple_protocol_iface_status_types(PurpleProtocol *, PurpleAccount *account); /** @copydoc _PurpleProtocolInterface::blist_node_menu */ GList *purple_protocol_iface_blist_node_menu(PurpleProtocol *, PurpleBlistNode *node); /** @copydoc _PurpleProtocolInterface::chat_info */ GList *purple_protocol_iface_chat_info(PurpleProtocol *, PurpleConnection *); /** @copydoc _PurpleProtocolInterface::chat_info_defaults */ GHashTable *purple_protocol_iface_chat_info_defaults(PurpleProtocol *, PurpleConnection *, const char *chat_name); /** @copydoc _PurpleProtocolInterface::login */ void purple_protocol_iface_login(PurpleProtocol *, PurpleAccount *); /** @copydoc _PurpleProtocolInterface::close */ void purple_protocol_iface_close(PurpleProtocol *, PurpleConnection *); /** @copydoc _PurpleProtocolInterface::send_im */ int purple_protocol_iface_send_im(PurpleProtocol *, PurpleConnection *, const char *who, const char *message, PurpleMessageFlags flags); /** @copydoc _PurpleProtocolInterface::set_info */ void purple_protocol_iface_set_info(PurpleProtocol *, PurpleConnection *, const char *info); /** @copydoc _PurpleProtocolInterface::send_typing */ unsigned int purple_protocol_iface_send_typing(PurpleProtocol *, PurpleConnection *, const char *name, PurpleIMTypingState state); /** @copydoc _PurpleProtocolInterface::get_info */ void purple_protocol_iface_get_info(PurpleProtocol *, PurpleConnection *, const char *who); /** @copydoc _PurpleProtocolInterface::set_status */ void purple_protocol_iface_set_status(PurpleProtocol *, PurpleAccount *account, PurpleStatus *status); /** @copydoc _PurpleProtocolInterface::set_idle */ void purple_protocol_iface_set_idle(PurpleProtocol *, PurpleConnection *, int idletime); /** @copydoc _PurpleProtocolInterface::change_passwd */ void purple_protocol_iface_change_passwd(PurpleProtocol *, PurpleConnection *, const char *old_pass, const char *new_pass); /** @copydoc _PurpleProtocolInterface::add_buddy */ void purple_protocol_iface_add_buddy(PurpleProtocol *, PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message); /** @copydoc _PurpleProtocolInterface::add_buddies */ void purple_protocol_iface_add_buddies(PurpleProtocol *, PurpleConnection *pc, GList *buddies, GList *groups, const char *message); /** @copydoc _PurpleProtocolInterface::remove_buddy */ void purple_protocol_iface_remove_buddy(PurpleProtocol *, PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group); /** @copydoc _PurpleProtocolInterface::remove_buddies */ void purple_protocol_iface_remove_buddies(PurpleProtocol *, PurpleConnection *, GList *buddies, GList *groups); /** @copydoc _PurpleProtocolInterface::add_permit */ void purple_protocol_iface_add_permit(PurpleProtocol *, PurpleConnection *, const char *name); /** @copydoc _PurpleProtocolInterface::add_deny */ void purple_protocol_iface_add_deny(PurpleProtocol *, PurpleConnection *, const char *name); /** @copydoc _PurpleProtocolInterface::rem_permit */ void purple_protocol_iface_rem_permit(PurpleProtocol *, PurpleConnection *, const char *name); /** @copydoc _PurpleProtocolInterface::rem_deny */ void purple_protocol_iface_rem_deny(PurpleProtocol *, PurpleConnection *, const char *name); /** @copydoc _PurpleProtocolInterface::set_permit_deny */ void purple_protocol_iface_set_permit_deny(PurpleProtocol *, PurpleConnection *); /** @copydoc _PurpleProtocolInterface::join_chat */ void purple_protocol_iface_join_chat(PurpleProtocol *, PurpleConnection *, GHashTable *components); /** @copydoc _PurpleProtocolInterface::reject_chat */ void purple_protocol_iface_reject_chat(PurpleProtocol *, PurpleConnection *, GHashTable *components); /** @copydoc _PurpleProtocolInterface::get_chat_name */ char *purple_protocol_iface_get_chat_name(PurpleProtocol *, GHashTable *components); /** @copydoc _PurpleProtocolInterface::chat_invite */ void purple_protocol_iface_chat_invite(PurpleProtocol *, PurpleConnection *, int id, const char *message, const char *who); /** @copydoc _PurpleProtocolInterface::chat_leave */ void purple_protocol_iface_chat_leave(PurpleProtocol *, PurpleConnection *, int id); /** @copydoc _PurpleProtocolInterface::chat_whisper */ void purple_protocol_iface_chat_whisper(PurpleProtocol *, PurpleConnection *, int id, const char *who, const char *message); /** @copydoc _PurpleProtocolInterface::chat_send */ int purple_protocol_iface_chat_send(PurpleProtocol *, PurpleConnection *, int id, const char *message, PurpleMessageFlags flags); /** @copydoc _PurpleProtocolInterface::keepalive */ void purple_protocol_iface_keepalive(PurpleProtocol *, PurpleConnection *); /** @copydoc _PurpleProtocolInterface::register_user */ void purple_protocol_iface_register_user(PurpleProtocol *, PurpleAccount *); /** @copydoc _PurpleProtocolInterface::unregister_user */ void purple_protocol_iface_unregister_user(PurpleProtocol *, PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data); /** @copydoc _PurpleProtocolInterface::get_cb_info */ void purple_protocol_iface_get_cb_info(PurpleProtocol *, PurpleConnection *, int, const char *who); /** @copydoc _PurpleProtocolInterface::alias_buddy */ void purple_protocol_iface_alias_buddy(PurpleProtocol *, PurpleConnection *, const char *who, const char *alias); /** @copydoc _PurpleProtocolInterface::group_buddy */ void purple_protocol_iface_group_buddy(PurpleProtocol *, PurpleConnection *, const char *who, const char *old_group, const char *new_group); /** @copydoc _PurpleProtocolInterface::rename_group */ void purple_protocol_iface_rename_group(PurpleProtocol *, PurpleConnection *, const char *old_name, PurpleGroup *group, GList *moved_buddies); /** @copydoc _PurpleProtocolInterface::buddy_free */ void purple_protocol_iface_buddy_free(PurpleProtocol *, PurpleBuddy *); /** @copydoc _PurpleProtocolInterface::convo_closed */ void purple_protocol_iface_convo_closed(PurpleProtocol *, PurpleConnection *, const char *who); /** @copydoc _PurpleProtocolInterface::normalize */ const char *purple_protocol_iface_normalize(PurpleProtocol *, const PurpleAccount *account, const char *who); /** @copydoc _PurpleProtocolInterface::set_buddy_icon */ void purple_protocol_iface_set_buddy_icon(PurpleProtocol *, PurpleConnection *, PurpleStoredImage *img); /** @copydoc _PurpleProtocolInterface::remove_group */ void purple_protocol_iface_remove_group(PurpleProtocol *, PurpleConnection *gc, PurpleGroup *group); /** @copydoc _PurpleProtocolInterface::get_cb_real_name */ char *purple_protocol_iface_get_cb_real_name(PurpleProtocol *, PurpleConnection *gc, int id, const char *who); /** @copydoc _PurpleProtocolInterface::set_chat_topic */ void purple_protocol_iface_set_chat_topic(PurpleProtocol *, PurpleConnection *gc, int id, const char *topic); /** @copydoc _PurpleProtocolInterface::find_blist_chat */ PurpleChat *purple_protocol_iface_find_blist_chat(PurpleProtocol *, PurpleAccount *account, const char *name); /** @copydoc _PurpleProtocolInterface::roomlist_get_list */ PurpleRoomlist *purple_protocol_iface_roomlist_get_list(PurpleProtocol *, PurpleConnection *gc); /** @copydoc _PurpleProtocolInterface::roomlist_cancel */ void purple_protocol_iface_roomlist_cancel(PurpleProtocol *, PurpleRoomlist *list); /** @copydoc _PurpleProtocolInterface::roomlist_expand_category */ void purple_protocol_iface_roomlist_expand_category( PurpleProtocol *, PurpleRoomlist *list, PurpleRoomlistRoom *category); /** @copydoc _PurpleProtocolInterface::can_receive_file */ gboolean purple_protocol_iface_can_receive_file(PurpleProtocol *, PurpleConnection *, const char *who); /** @copydoc _PurpleProtocolInterface::send_file */ void purple_protocol_iface_send_file(PurpleProtocol *, PurpleConnection *, const char *who, const char *filename); /** @copydoc _PurpleProtocolInterface::new_xfer */ PurpleXfer *purple_protocol_iface_new_xfer(PurpleProtocol *, PurpleConnection *, const char *who); /** @copydoc _PurpleProtocolInterface::offline_message */ gboolean purple_protocol_iface_offline_message(PurpleProtocol *, const PurpleBuddy *buddy); /** @copydoc _PurpleProtocolInterface::send_raw */ int purple_protocol_iface_send_raw(PurpleProtocol *, PurpleConnection *gc, const char *buf, int len); /** @copydoc _PurpleProtocolInterface::roomlist_room_serialize */ char *purple_protocol_iface_roomlist_room_serialize(PurpleProtocol *, PurpleRoomlistRoom *room); /** @copydoc _PurpleProtocolInterface::send_attention */ gboolean purple_protocol_iface_send_attention(PurpleProtocol *, PurpleConnection *gc, const char *username, guint type); /** @copydoc _PurpleProtocolInterface::get_attention_types */ GList *purple_protocol_iface_get_attention_types(PurpleProtocol *, PurpleAccount *acct); /** @copydoc _PurpleProtocolInterface::get_account_text_table */ GHashTable *purple_protocol_iface_get_account_text_table( PurpleProtocol *, PurpleAccount *account); /** @copydoc _PurpleProtocolInterface::initiate_media */ gboolean purple_protocol_iface_initiate_media(PurpleProtocol *, PurpleAccount *account, const char *who, PurpleMediaSessionType type); /** @copydoc _PurpleProtocolInterface::get_media_caps */ PurpleMediaCaps purple_protocol_iface_get_media_caps(PurpleProtocol *, PurpleAccount *account, const char *who); /** @copydoc _PurpleProtocolInterface::get_moods */ PurpleMood *purple_protocol_iface_get_moods(PurpleProtocol *, PurpleAccount *account); /** @copydoc _PurpleProtocolInterface::set_public_alias */ void purple_protocol_iface_set_public_alias( PurpleProtocol *, PurpleConnection *gc, const char *alias, PurpleSetPublicAliasSuccessCallback success_cb, PurpleSetPublicAliasFailureCallback failure_cb); /** @copydoc _PurpleProtocolInterface::get_public_alias */ void purple_protocol_iface_get_public_alias( PurpleProtocol *, PurpleConnection *gc, PurpleGetPublicAliasSuccessCallback success_cb, PurpleGetPublicAliasFailureCallback failure_cb); /** @copydoc _PurpleProtocolInterface::get_max_message_size */ gsize purple_protocol_iface_get_max_message_size(PurpleProtocol *, PurpleConnection *gc); /*@}*/ G_END_DECLS #endif /* _PROTOCOL_H_ */
