diff options
author | Ankit Vani <a@nevitus.org> | 2014-02-06 20:02:57 +0530 |
---|---|---|
committer | Ankit Vani <a@nevitus.org> | 2014-02-06 20:02:57 +0530 |
commit | bc39db29f1e8035e865d7a63b682d9af789060d0 (patch) | |
tree | 6755b42a6b4f3be6b92324fcc5398c79880443f0 /libpurple/protocols.h | |
parent | e7a9a05d1ab0c622825536c19c00fa9e2485d94b (diff) | |
parent | 4d48f25ec36c7d7c6782e4597513f9ee7e21c33a (diff) | |
download | pidgin-bc39db29f1e8035e865d7a63b682d9af789060d0.tar.gz |
Merge gtkdoc-conversion
Diffstat (limited to 'libpurple/protocols.h')
-rw-r--r-- | libpurple/protocols.h | 678 |
1 files changed, 678 insertions, 0 deletions
diff --git a/libpurple/protocols.h b/libpurple/protocols.h new file mode 100644 index 0000000000..af4ca94f8e --- /dev/null +++ b/libpurple/protocols.h @@ -0,0 +1,678 @@ +/* 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 + */ +/** + * SECTION:protocols + * @section_id: libpurple-protocols + * @short_description: <filename>protocols.h</filename> + * @title: Protocols Subsystem API + * @see_also: <link linkend="chapter-signals-protocol">Protocol signals</link> + */ + +#ifndef _PURPLE_PROTOCOLS_H_ +#define _PURPLE_PROTOCOLS_H_ + +#define PURPLE_PROTOCOLS_DOMAIN (g_quark_from_static_string("protocols")) + +#define PURPLE_TYPE_PROTOCOL_ACTION (purple_protocol_action_get_type()) + +typedef struct _PurpleProtocolAction PurpleProtocolAction; +typedef void (*PurpleProtocolActionCallback)(PurpleProtocolAction *); + +#define PURPLE_TYPE_ATTENTION_TYPE (purple_attention_type_get_type()) + +/** + * PurpleAttentionType: + * + * Represents "nudges" and "buzzes" that you may send to a buddy to attract + * their attention (or vice-versa). + */ +typedef struct _PurpleAttentionType PurpleAttentionType; + +/**************************************************************************/ +/* Basic Protocol Information */ +/**************************************************************************/ + +/** + * PurpleIconScaleRules: + * @PURPLE_ICON_SCALE_DISPLAY: We scale the icon when we display it + * @PURPLE_ICON_SCALE_SEND: We scale the icon before we send it to the server + */ +typedef enum /*< flags >*/ +{ + PURPLE_ICON_SCALE_DISPLAY = 0x01, + PURPLE_ICON_SCALE_SEND = 0x02 + +} PurpleIconScaleRules; + +typedef struct _PurpleProtocolChatEntry PurpleProtocolChatEntry; + +/** + * PurpleProtocolOptions: + * @OPT_PROTO_UNIQUE_CHATNAME: User names are unique to a chat and are not + * shared between rooms.<sbr/> + * XMPP lets you choose what name you want in chats, so it shouldn't + * be pulling the aliases from the buddy list for the chat list; it + * gets annoying. + * @OPT_PROTO_CHAT_TOPIC: Chat rooms have topics.<sbr/> + * IRC and XMPP support this. + * @OPT_PROTO_NO_PASSWORD: Don't require passwords for sign-in.<sbr/> + * Zephyr doesn't require passwords, so there's no need for a + * password prompt. + * @OPT_PROTO_MAIL_CHECK: Notify on new mail.<sbr/> + * MSN and Yahoo notify you when you have new mail. + * @OPT_PROTO_IM_IMAGE: Images in IMs.<sbr/> + * Oscar lets you send images in direct IMs. + * @OPT_PROTO_PASSWORD_OPTIONAL: Allow passwords to be optional.<sbr/> + * Passwords in IRC are optional, and are needed for certain + * functionality. + * @OPT_PROTO_USE_POINTSIZE: Allows font size to be specified in sane point + * size.<sbr/> + * Probably just XMPP and Y!M + * @OPT_PROTO_REGISTER_NOSCREENNAME: Set the Register button active even when + * the username has not been specified.<sbr/> + * Gadu-Gadu doesn't need a username to register new account (because + * usernames are assigned by the server). + * @OPT_PROTO_SLASH_COMMANDS_NATIVE: Indicates that slash commands are native + * to this protocol.<sbr/> + * Used as a hint that unknown commands should not be sent as + * messages. + * @OPT_PROTO_INVITE_MESSAGE: Indicates that this protocol supports sending a + * user-supplied message along with an invitation. + * @OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE: Indicates that this protocol + * supports sending a user-supplied message along with an + * authorization acceptance. + * @OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE: Indicates that this protocol + * supports sending a user-supplied message along with an + * authorization denial. + * + * Protocol options + * + * These should all be stuff that some protocols can do and others can't. + */ +typedef enum /*< flags >*/ +{ + OPT_PROTO_UNIQUE_CHATNAME = 0x00000004, + OPT_PROTO_CHAT_TOPIC = 0x00000008, + OPT_PROTO_NO_PASSWORD = 0x00000010, + OPT_PROTO_MAIL_CHECK = 0x00000020, + OPT_PROTO_IM_IMAGE = 0x00000040, + OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080, + OPT_PROTO_USE_POINTSIZE = 0x00000100, + OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200, + OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400, + OPT_PROTO_INVITE_MESSAGE = 0x00000800, + OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE = 0x00001000, + OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE = 0x00002000 + +} PurpleProtocolOptions; + +#include "media.h" +#include "protocol.h" +#include "status.h" + +#define PURPLE_TYPE_PROTOCOL_CHAT_ENTRY (purple_protocol_chat_entry_get_type()) + +/** + * PurpleProtocolChatEntry: + * @label: User-friendly name of the entry + * @identifier: Used by the protocol to identify the option + * @required: True if it's required + * @is_int: True if the entry expects an integer + * @min: Minimum value in case of integer + * @max: Maximum value in case of integer + * @secret: True if the entry is secret (password) + * + * Represents an entry containing information that must be supplied by the + * user when joining a chat. + */ +struct _PurpleProtocolChatEntry { + const char *label; + const char *identifier; + gboolean required; + gboolean is_int; + int min; + int max; + gboolean secret; +}; + +/** + * PurpleProtocolAction: + * + * Represents an action that the protocol can perform. This shows up in the + * Accounts menu, under a submenu with the name of the account. + */ +struct _PurpleProtocolAction { + char *label; + PurpleProtocolActionCallback callback; + PurpleConnection *connection; + gpointer user_data; +}; + +G_BEGIN_DECLS + +/**************************************************************************/ +/* Attention Type API */ +/**************************************************************************/ +/*@{*/ + +/** + * purple_attention_type_get_type: + * + * Returns: The #GType for the #PurpleAttentionType boxed structure. + */ +GType purple_attention_type_get_type(void); + +/** + * purple_attention_type_new: + * @ulname: A non-localized string that can be used by UIs in need of such + * non-localized strings. This should be the same as @name, + * without localization. + * @name: A localized string that the UI may display for the event. This + * should be the same string as @ulname, with localization. + * @inc_desc: A localized description shown when the event is received. + * @out_desc: A localized description shown when the event is sent. + * + * Creates a new #PurpleAttentionType object and sets its mandatory parameters. + * + * Returns: A pointer to the new object. + */ +PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name, + const char *inc_desc, const char *out_desc); + +/** + * purple_attention_type_set_name: + * @type: The attention type. + * @name: The localized name that will be displayed by UIs. This should be + * the same string given as the unlocalized name, but with + * localization. + * + * Sets the displayed name of the attention-demanding event. + */ +void purple_attention_type_set_name(PurpleAttentionType *type, const char *name); + +/** + * purple_attention_type_set_incoming_desc: + * @type: The attention type. + * @desc: The localized description for incoming events. + * + * Sets the description of the attention-demanding event shown in conversations + * when the event is received. + */ +void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc); + +/** + * purple_attention_type_set_outgoing_desc: + * @type: The attention type. + * @desc: The localized description for outgoing events. + * + * Sets the description of the attention-demanding event shown in conversations + * when the event is sent. + */ +void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc); + +/** + * purple_attention_type_set_icon_name: + * @type: The attention type. + * @name: The icon's name. + * + * Sets the name of the icon to display for the attention event; this is optional. + * + * Note: Icons are optional for attention events. + */ +void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name); + +/** + * purple_attention_type_set_unlocalized_name: + * @type: The attention type. + * @ulname: The unlocalized name. This should be the same string given as + * the localized name, but without localization. + * + * Sets the unlocalized name of the attention event; some UIs may need this, + * thus it is required. + */ +void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname); + +/** + * purple_attention_type_get_name: + * @type: The attention type. + * + * Get the attention type's name as displayed by the UI. + * + * Returns: The name. + */ +const char *purple_attention_type_get_name(const PurpleAttentionType *type); + +/** + * purple_attention_type_get_incoming_desc: + * @type: The attention type. + * + * Get the attention type's description shown when the event is received. + * + * Returns: The description. + */ +const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type); + +/** + * purple_attention_type_get_outgoing_desc: + * @type: The attention type. + * + * Get the attention type's description shown when the event is sent. + * + * Returns: The description. + */ +const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type); + +/** + * purple_attention_type_get_icon_name: + * @type: The attention type. + * + * Get the attention type's icon name. + * + * Note: Icons are optional for attention events. + * + * Returns: The icon name or %NULL if unset/empty. + */ +const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type); + +/** + * purple_attention_type_get_unlocalized_name: + * @type: The attention type + * + * Get the attention type's unlocalized name; this is useful for some UIs. + * + * Returns: The unlocalized name. + */ +const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type); + +/*@}*/ + +/**************************************************************************/ +/* Protocol Action API */ +/**************************************************************************/ +/*@{*/ + +/** + * purple_protocol_action_get_type: + * + * Returns: The #GType for the #PurpleProtocolAction boxed structure. + */ +GType purple_protocol_action_get_type(void); + +/** + * purple_protocol_action_new: + * @label: The description of the action to show to the user. + * @callback: The callback to call when the user selects this action. + * + * Allocates and returns a new PurpleProtocolAction. Use this to add actions in + * a list in the get_actions function of the protocol. + */ +PurpleProtocolAction *purple_protocol_action_new(const char* label, + PurpleProtocolActionCallback callback); + +/** + * purple_protocol_action_free: + * @action: The PurpleProtocolAction to free. + * + * Frees a PurpleProtocolAction + */ +void purple_protocol_action_free(PurpleProtocolAction *action); + +/*@}*/ + +/**************************************************************************/ +/** @name Protocol Chat Entry API */ +/**************************************************************************/ +/*@{*/ + +/** + * purple_protocol_chat_entry_get_type: + * + * Returns: The #GType for the #PurpleProtocolChatEntry boxed structure. + */ +GType purple_protocol_chat_entry_get_type(void); + +/*@}*/ + +/**************************************************************************/ +/** @name Protocol API */ +/**************************************************************************/ +/*@{*/ + +/** + * purple_protocol_got_account_idle: + * @account: The account. + * @idle: The user's idle state. + * @idle_time: The user's idle time. + * + * Notifies Purple that our account's idle state and time have changed. + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_account_idle(PurpleAccount *account, gboolean idle, + time_t idle_time); + +/** + * purple_protocol_got_account_login_time: + * @account: The account the user is on. + * @login_time: The user's log-in time. + * + * Notifies Purple of our account's log-in time. + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_account_login_time(PurpleAccount *account, + time_t login_time); + +/** + * purple_protocol_got_account_status: + * @account: The account the user is on. + * @status_id: The status ID. + * @...: A NULL-terminated list of attribute IDs and values, + * beginning with the value for %attr_id. + * + * Notifies Purple that our account's status has changed. + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_account_status(PurpleAccount *account, + const char *status_id, ...) + G_GNUC_NULL_TERMINATED; + +/** + * purple_protocol_got_account_actions: + * @account: The account. + * + * 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. + * + * See <link linkend="accounts-account-actions-changed"><literal>"account-actions-changed"</literal></link> + */ +void purple_protocol_got_account_actions(PurpleAccount *account); + +/** + * purple_protocol_got_user_idle: + * @account: The account the user is on. + * @name: The name of the buddy. + * @idle: The user's idle state. + * @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. + * + * Notifies Purple that a buddy's idle state and time have changed. + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_user_idle(PurpleAccount *account, const char *name, + gboolean idle, time_t idle_time); + +/** + * purple_protocol_got_user_login_time: + * @account: The account the user is on. + * @name: The name of the buddy. + * @login_time: The user's log-in time. + * + * Notifies Purple of a buddy's log-in time. + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_user_login_time(PurpleAccount *account, + const char *name, time_t login_time); + +/** + * purple_protocol_got_user_status: + * @account: The account the user is on. + * @name: The name of the buddy. + * @status_id: The status ID. + * @...: A NULL-terminated list of attribute IDs and values, + * beginning with the value for %attr_id. + * + * Notifies Purple that a buddy's status has been activated. + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_user_status(PurpleAccount *account, const char *name, + const char *status_id, ...) + G_GNUC_NULL_TERMINATED; + +/** + * purple_protocol_got_user_status_deactive: + * @account: The account the user is on. + * @name: The name of the buddy. + * @status_id: The status ID. + * + * Notifies libpurple that a buddy's status has been deactivated + * + * This is meant to be called from protocols. + */ +void purple_protocol_got_user_status_deactive(PurpleAccount *account, + const char *name, + const char *status_id); + +/** + * purple_protocol_change_account_status: + * @account: The account the user is on. + * @old_status: The previous status. + * @new_status: The status that was activated, or deactivated + * (in the case of independent statuses). + * + * Informs the server that our account's status changed. + */ +void purple_protocol_change_account_status(PurpleAccount *account, + PurpleStatus *old_status, + PurpleStatus *new_status); + +/** + * purple_protocol_get_statuses: + * @account: The account the user is on. + * @presence: The presence for which we're going to get statuses + * + * Retrieves the list of stock status types from a protocol. + * + * Returns: List of statuses + */ +GList *purple_protocol_get_statuses(PurpleAccount *account, + PurplePresence *presence); + +/** + * purple_protocol_send_attention: + * @gc: The connection to send the message on. + * @who: Whose attention to request. + * @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). + * + * Send an attention request message. + * + * 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); + +/** + * purple_protocol_got_attention: + * @gc: The connection that received the attention message. + * @who: Who requested your attention. + * @type_code: An index into the protocol's attention_types list + * determining the type of the attention request command to + * send. + * + * Process an incoming attention message. + */ +void purple_protocol_got_attention(PurpleConnection *gc, const char *who, + guint type_code); + +/** + * purple_protocol_got_attention_in_chat: + * @gc: The connection that received the attention message. + * @id: The chat id. + * @who: Who requested your attention. + * @type_code: An index into the protocol's attention_types list + * determining the type of the attention request command to + * send. + * + * Process an incoming attention message in a chat. + */ +void purple_protocol_got_attention_in_chat(PurpleConnection *gc, int id, + const char *who, guint type_code); + +/** + * purple_protocol_get_media_caps: + * @account: The account the user is on. + * @who: The name of the contact to check capabilities for. + * + * Determines if the contact supports the given media session type. + * + * Returns: The media caps the contact supports. + */ +PurpleMediaCaps purple_protocol_get_media_caps(PurpleAccount *account, + const char *who); + +/** + * purple_protocol_initiate_media: + * @account: The account the user is on. + * @who: The name of the contact to start a session with. + * @type: The type of media session to start. + * + * Initiates a media session with the given contact. + * + * Returns: 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); + +/** + * purple_protocol_got_media_caps: + * @account: The account the user is on. + * @who: The name of the contact for which capabilities have been received. + * + * Signals that the protocol received capabilities for the given contact. + * + * This function is intended to be used only by protocols. + */ +void purple_protocol_got_media_caps(PurpleAccount *account, const char *who); + +/** + * purple_protocol_get_max_message_size: + * @protocol: The protocol to query. + * + * Gets the safe maximum message size in bytes for the protocol. + * + * See #PurpleProtocol.get_max_message_size + * + * Returns: Maximum message size, 0 if unspecified, -1 for infinite. + */ +gssize +purple_protocol_get_max_message_size(PurpleProtocol *protocol); + +/*@}*/ + +/**************************************************************************/ +/* Protocols API */ +/**************************************************************************/ +/*@{*/ + +/** + * purple_protocols_find: + * @id: The protocol's ID. + * + * Finds a protocol by ID. + */ +PurpleProtocol *purple_protocols_find(const char *id); + +/** + * purple_protocols_add: + * @protocol_type: The type of the protocol to add. + * @error: Return location for a #GError or %NULL. If provided, this + * will be set to the reason if adding fails. + * + * Adds a protocol to the list of protocols. + * + * Returns: The protocol instance if the protocol was added, else %NULL. + */ +PurpleProtocol *purple_protocols_add(GType protocol_type, GError **error); + +/** + * purple_protocols_remove: + * @protocol: The protocol to remove. + * @error: Return location for a #GError or %NULL. If provided, this + * will be set to the reason if removing fails. + * + * Removes a protocol from the list of protocols. This will disconnect all + * connected accounts using this protocol, and free the protocol's user splits + * and protocol options. + * + * Returns: TRUE if the protocol was removed, else FALSE. + */ +gboolean purple_protocols_remove(PurpleProtocol *protocol, GError **error); + +/** + * purple_protocols_get_all: + * + * Returns a list of all loaded protocols. + * + * Returns: A list of all loaded protocols. The list is owned by the caller, and + * must be g_list_free()d to avoid leaking the nodes. + */ +GList *purple_protocols_get_all(void); + +/*@}*/ + +/**************************************************************************/ +/** @name Protocols Subsytem API */ +/**************************************************************************/ +/*@{*/ + +/** + * purple_protocols_init: + * + * Initializes the protocols subsystem. + */ +void purple_protocols_init(void); + +/** + * purple_protocols_get_handle: + * + * Returns the protocols subsystem handle. + * + * Returns: The protocols subsystem handle. + */ +void *purple_protocols_get_handle(void); + +/** + * purple_protocols_uninit: + * + * Uninitializes the protocols subsystem. + */ +void purple_protocols_uninit(void); + +/*@}*/ + +G_END_DECLS + +#endif /* _PROTOCOLS_H_ */ |