* 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
* 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
#if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
# error "only <purple.h> may be included directly"
#ifndef PURPLE_PROTOCOLS_H
#define PURPLE_PROTOCOLS_H
* @section_id: libpurple-protocols
* @short_description: <filename>protocols.h</filename>
* @title: Protocols Subsystem API
* @see_also: <link linkend="chapter-signals-protocol">Protocol signals</link>
#define PURPLE_PROTOCOLS_DOMAIN (g_quark_from_static_string("protocols"))
/**************************************************************************/
/* Basic Protocol Information */
/**************************************************************************/
typedef struct _PurpleProtocolChatEntry PurpleProtocolChatEntry;
* @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
* @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
* @OPT_PROTO_MAIL_CHECK: Notify on new mail.<sbr/>
* MSN and Yahoo notify you when you have new mail.
* @OPT_PROTO_PASSWORD_OPTIONAL: Allow passwords to be optional.<sbr/>
* Passwords in IRC are optional, and are needed for certain
* @OPT_PROTO_USE_POINTSIZE: Allows font size to be specified in sane point
* 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
* @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
* 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_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
#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 {
/**************************************************************************/
/**************************************************************************/
/**************************************************************************/
/* 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);
/**************************************************************************/
/**************************************************************************/
* purple_protocol_got_account_idle:
* @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,
* 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,
* 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 <literal>attr_id</literal>.
* 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, ...)
* purple_protocol_got_account_actions:
* Notifies Purple that our account's actions have changed. This is only
* called after the initial connection. Emits the account-actions-changed
* 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
* 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 <literal>attr_id</literal>.
* 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, ...)
* 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,
* 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: (transfer full) (element-type PurpleStatus): 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 protocols are allowed to define more.
* 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,
* 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
* Process an incoming attention message.
void purple_protocol_got_attention(PurpleConnection *gc, const char *who,
* purple_protocol_got_attention_in_chat:
* @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
* 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,
* 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,
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 #PurpleProtocolClientInterface's <literal>get_max_message_size</literal>.
* Returns: Maximum message size, 0 if unspecified, -1 for infinite.
purple_protocol_get_max_message_size(PurpleProtocol *protocol);
/**************************************************************************/
/**************************************************************************/
* @id: The protocol's ID.
* Finds a protocol by ID.
* Returns: (transfer none): The protocol, if found, or %NULL otherwise.
PurpleProtocol *purple_protocols_find(const char *id);
* @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: (transfer none): The protocol instance if the protocol was added,
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
* 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: (element-type PurpleProtocol) (transfer container): A list of all
GList *purple_protocols_get_all(void);
/**************************************************************************/
/* Protocols Subsytem API */
/**************************************************************************/
* 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);
#endif /* PURPLE_PROTOCOLS_H */
