Protocol Plugin functions. More...

#include "blist.h"
#include "conversation.h"
#include "ft.h"
#include "imgstore.h"
#include "media.h"
#include "notify.h"
#include "proxy.h"
#include "plugin.h"
#include "roomlist.h"
#include "status.h"
#include "whiteboard.h"

Include dependency graph for prpl.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	_PurpleBuddyIconSpec
	A description of a Buddy Icon specification. More...

struct	proto_chat_entry
	Represents an entry containing information that must be supplied by the user when joining a chat. More...

struct	_PurpleAttentionType
	Represents "nudges" and "buzzes" that you may send to a buddy to attract their attention (or vice-versa). More...

struct	_PurplePluginProtocolInfo
	A protocol plugin information structure. More...

Typedefs
typedef struct _PurplePluginProtocolInfo	PurplePluginProtocolInfo

typedef struct _PurpleAttentionType	PurpleAttentionType
	Represents "nudges" and "buzzes" that you may send to a buddy to attract their attention (or vice-versa).

Functions
Attention Type API <br>
PurpleAttentionType *	purple_attention_type_new (const char ulname, const char name, const char inc_desc, const char out_desc)
	Creates a new PurpleAttentionType object and sets its mandatory parameters.

void	purple_attention_type_set_name (PurpleAttentionType type, const char name)
	Sets the displayed name of the attention-demanding event.

void	purple_attention_type_set_incoming_desc (PurpleAttentionType type, const char desc)
	Sets the description of the attention-demanding event shown in conversations when the event is received.

void	purple_attention_type_set_outgoing_desc (PurpleAttentionType type, const char desc)
	Sets the description of the attention-demanding event shown in conversations when the event is sent.

void	purple_attention_type_set_icon_name (PurpleAttentionType type, const char name)
	Sets the name of the icon to display for the attention event; this is optional.

void	purple_attention_type_set_unlocalized_name (PurpleAttentionType type, const char ulname)
	Sets the unlocalized name of the attention event; some UIs may need this, thus it is required.

const char *	purple_attention_type_get_name (const PurpleAttentionType *type)
	Get the attention type's name as displayed by the UI.

const char *	purple_attention_type_get_incoming_desc (const PurpleAttentionType *type)
	Get the attention type's description shown when the event is received.

const char *	purple_attention_type_get_outgoing_desc (const PurpleAttentionType *type)
	Get the attention type's description shown when the event is sent.

const char *	purple_attention_type_get_icon_name (const PurpleAttentionType *type)
	Get the attention type's icon name.

const char *	purple_attention_type_get_unlocalized_name (const PurpleAttentionType *type)
	Get the attention type's unlocalized name; this is useful for some UIs.

Protocol Plugin API <br>
void	purple_prpl_got_account_idle (PurpleAccount *account, gboolean idle, time_t idle_time)
	Notifies Purple that our account's idle state and time have changed.

void	purple_prpl_got_account_login_time (PurpleAccount *account, time_t login_time)
	Notifies Purple of our account's log-in time.

void	purple_prpl_got_account_status (PurpleAccount account, const char status_id,...) G_GNUC_NULL_TERMINATED
	Notifies Purple that our account's status has changed.

void	purple_prpl_got_account_actions (PurpleAccount *account)
	Notifies Purple that our account's actions have changed.

void	purple_prpl_got_user_idle (PurpleAccount account, const char name, gboolean idle, time_t idle_time)
	Notifies Purple that a buddy's idle state and time have changed.

void	purple_prpl_got_user_login_time (PurpleAccount account, const char name, time_t login_time)
	Notifies Purple of a buddy's log-in time.

void	purple_prpl_got_user_status (PurpleAccount account, const char name, const char *status_id,...) G_GNUC_NULL_TERMINATED
	Notifies Purple that a buddy's status has been activated.

void	purple_prpl_got_user_status_deactive (PurpleAccount account, const char name, const char *status_id)
	Notifies libpurple that a buddy's status has been deactivated.

void	purple_prpl_change_account_status (PurpleAccount account, PurpleStatus old_status, PurpleStatus *new_status)
	Informs the server that our account's status changed.

GList *	purple_prpl_get_statuses (PurpleAccount account, PurplePresence presence)
	Retrieves the list of stock status types from a prpl.

void	purple_prpl_send_attention (PurpleConnection gc, const char who, guint type_code)
	Send an attention request message.

void	purple_prpl_got_attention (PurpleConnection gc, const char who, guint type_code)
	Process an incoming attention message.

void	purple_prpl_got_attention_in_chat (PurpleConnection gc, int id, const char who, guint type_code)
	Process an incoming attention message in a chat.

PurpleMediaCaps	purple_prpl_get_media_caps (PurpleAccount account, const char who)
	Determines if the contact supports the given media session type.

gboolean	purple_prpl_initiate_media (PurpleAccount account, const char who, PurpleMediaSessionType type)
	Initiates a media session with the given contact.

void	purple_prpl_got_media_caps (PurpleAccount account, const char who)
	Signals that the prpl received capabilities for the given contact.

Protocol Plugin Subsystem API <br>
PurplePlugin *	purple_find_prpl (const char *id)
	Finds a protocol plugin structure of the specified type.

Basic Protocol Information <br>
#define	NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
	This #define exists just to make it easier to fill out the buddy icon field in the prpl info struct for protocols that couldn't care less.

#define	PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member)

#define	PURPLE_IS_PROTOCOL_PLUGIN(plugin) ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)

#define	PURPLE_PLUGIN_PROTOCOL_INFO(plugin) ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)

enum	PurpleIconScaleRules { PURPLE_ICON_SCALE_DISPLAY = 0x01 , PURPLE_ICON_SCALE_SEND = 0x02 }

enum	PurpleProtocolOptions { 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_TRANSIENT_BUDDIES = 0x00001000 }
	Protocol options. More...

typedef struct _PurpleBuddyIconSpec	PurpleBuddyIconSpec
	A description of a Buddy Icon specification.

typedef struct _PurpleThumbnailSpec	PurpleThumbnailSpec
	A description of a file transfer thumbnail specification.

Detailed Description

Protocol Plugin functions.

Definition in file prpl.h.

Macro Definition Documentation

◆ NO_BUDDY_ICONS

#define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}

This #define exists just to make it easier to fill out the buddy icon field in the prpl info struct for protocols that couldn't care less.

Definition at line 65 of file prpl.h.

◆ PURPLE_IS_PROTOCOL_PLUGIN

#define PURPLE_IS_PROTOCOL_PLUGIN ( plugin ) ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)

Definition at line 702 of file prpl.h.

◆ PURPLE_PLUGIN_PROTOCOL_INFO

#define PURPLE_PLUGIN_PROTOCOL_INFO ( plugin ) ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)

Definition at line 705 of file prpl.h.

◆ PURPLE_PROTOCOL_PLUGIN_HAS_FUNC

#define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC	(	prpl,
		member
	)

Value:

    (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
      || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
     prpl->member != NULL)

Definition at line 696 of file prpl.h.

Typedef Documentation

◆ PurpleAttentionType

typedef struct _PurpleAttentionType PurpleAttentionType

Represents "nudges" and "buzzes" that you may send to a buddy to attract their attention (or vice-versa).

Definition at line 35 of file prpl.h.

◆ PurpleBuddyIconSpec

typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec

A description of a Buddy Icon specification.

This tells Purple what kind of image file it should give this prpl, and what kind of image file it should expect back. Dimensions less than 1 should be ignored and the image not scaled.

Definition at line 52 of file prpl.h.

◆ PurplePluginProtocolInfo

typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo

Definition at line 33 of file prpl.h.

◆ PurpleThumbnailSpec

typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec

A description of a file transfer thumbnail specification.

This tells the UI if and what image formats the prpl support for file transfer thumbnails.

Definition at line 59 of file prpl.h.

Enumeration Type Documentation

◆ PurpleIconScaleRules

enum PurpleIconScaleRules

Enumerator
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.

Definition at line 41 of file prpl.h.

◆ PurpleProtocolOptions

enum PurpleProtocolOptions

Protocol options.

These should all be stuff that some plugins can do and others can't.

Enumerator
OPT_PROTO_UNIQUE_CHATNAME	User names are unique to a chat and are not shared between rooms. 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. IRC and XMPP support this.
OPT_PROTO_NO_PASSWORD	Don't require passwords for sign-in. Zephyr doesn't require passwords, so there's no need for a password prompt.
OPT_PROTO_MAIL_CHECK	Notify on new mail. If a protocol notifies you when you have new mail.
OPT_PROTO_IM_IMAGE	Images in IMs. Oscar lets you send images in direct IMs.
OPT_PROTO_PASSWORD_OPTIONAL	Allow passwords to be optional. 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. Probably just XMPP and Y!M
OPT_PROTO_REGISTER_NOSCREENNAME	Set the Register button active even when the username has not been specified. 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. Used as a hint that unknown commands should not be sent as messages. Since 2.1.0
OPT_PROTO_INVITE_MESSAGE	Indicates that this protocol supports sending a user-supplied message along with an invitation. Since 2.8.0
OPT_PROTO_TRANSIENT_BUDDIES	Indicates that this protocol supports creating invisible buddies for reporting presence/alias of IM peers. Since 2.14.0

Definition at line 136 of file prpl.h.

Function Documentation

◆ purple_attention_type_get_icon_name()

const char * purple_attention_type_get_icon_name ( const PurpleAttentionType * type )

Get the attention type's icon name.

Parameters

type	The attention type.

Returns: The icon name or NULL if unset/empty.

Note: Icons are optional for attention events.

Since: 2.4.0

◆ purple_attention_type_get_incoming_desc()

const char * purple_attention_type_get_incoming_desc ( const PurpleAttentionType * type )

Get the attention type's description shown when the event is received.

Parameters

type	The attention type.

Returns: The description.

Since: 2.4.0

◆ purple_attention_type_get_name()

const char * purple_attention_type_get_name ( const PurpleAttentionType * type )

Get the attention type's name as displayed by the UI.

Parameters

type	The attention type.

Returns: The name.

Since: 2.4.0

◆ purple_attention_type_get_outgoing_desc()

const char * purple_attention_type_get_outgoing_desc ( const PurpleAttentionType * type )

Get the attention type's description shown when the event is sent.

Parameters

type	The attention type.

Returns: The description.

Since: 2.4.0

◆ purple_attention_type_get_unlocalized_name()

const char * purple_attention_type_get_unlocalized_name ( const PurpleAttentionType * type )

Get the attention type's unlocalized name; this is useful for some UIs.

Parameters

type	The attention type

Returns: The unlocalized name.

Since: 2.4.0

◆ purple_attention_type_new()

PurpleAttentionType * purple_attention_type_new	(	const char *	ulname,
		const char *	name,
		const char *	inc_desc,
		const char *	out_desc
	)

Creates a new PurpleAttentionType object and sets its mandatory parameters.

Parameters

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.

Returns: A pointer to the new object.

Since: 2.4.0

◆ purple_attention_type_set_icon_name()

void purple_attention_type_set_icon_name	(	PurpleAttentionType *	type,
		const char *	name
	)

Sets the name of the icon to display for the attention event; this is optional.

Parameters

type	The attention type.
name	The icon's name.

Note: Icons are optional for attention events.

Since: 2.4.0

◆ purple_attention_type_set_incoming_desc()

void purple_attention_type_set_incoming_desc	(	PurpleAttentionType *	type,
		const char *	desc
	)

Sets the description of the attention-demanding event shown in conversations when the event is received.

Parameters

type	The attention type.
desc	The localized description for incoming events.

Since: 2.4.0

◆ purple_attention_type_set_name()

void purple_attention_type_set_name	(	PurpleAttentionType *	type,
		const char *	name
	)

Sets the displayed name of the attention-demanding event.

Parameters

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.

Since: 2.4.0

◆ purple_attention_type_set_outgoing_desc()

void purple_attention_type_set_outgoing_desc	(	PurpleAttentionType *	type,
		const char *	desc
	)

Sets the description of the attention-demanding event shown in conversations when the event is sent.

Parameters

type	The attention type.
desc	The localized description for outgoing events.

Since: 2.4.0

◆ purple_attention_type_set_unlocalized_name()

void purple_attention_type_set_unlocalized_name	(	PurpleAttentionType *	type,
		const char *	ulname
	)

Sets the unlocalized name of the attention event; some UIs may need this, thus it is required.

Parameters

type	The attention type.
ulname	The unlocalized name. This should be the same string given as the localized name, but without localization.

Since: 2.4.0

◆ purple_find_prpl()

PurplePlugin * purple_find_prpl ( const char * id )

Finds a protocol plugin structure of the specified type.

Parameters

id	The protocol plugin;

◆ purple_prpl_change_account_status()

void purple_prpl_change_account_status	(	PurpleAccount *	account,
		PurpleStatus *	old_status,
		PurpleStatus *	new_status
	)

Informs the server that our account's status changed.

Parameters

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).

◆ purple_prpl_get_media_caps()

PurpleMediaCaps purple_prpl_get_media_caps	(	PurpleAccount *	account,
		const char *	who
	)

Determines if the contact supports the given media session type.

Parameters

account	The account the user is on.
who	The name of the contact to check capabilities for.

Returns: The media caps the contact supports.

◆ purple_prpl_get_statuses()

GList * purple_prpl_get_statuses	(	PurpleAccount *	account,
		PurplePresence *	presence
	)

Retrieves the list of stock status types from a prpl.

Parameters

account	The account the user is on.
presence	The presence for which we're going to get statuses

Returns: List of statuses

◆ purple_prpl_got_account_actions()

void purple_prpl_got_account_actions ( PurpleAccount * 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 protocol plugins.

Parameters

account The account.

See also: account-actions-changed

Since: 2.6.0

◆ purple_prpl_got_account_idle()

void purple_prpl_got_account_idle	(	PurpleAccount *	account,
		gboolean	idle,
		time_t	idle_time
	)

Notifies Purple that our account's idle state and time have changed.

This is meant to be called from protocol plugins.

Parameters

account	The account.
idle	The user's idle state.
idle_time	The user's idle time.

◆ purple_prpl_got_account_login_time()

void purple_prpl_got_account_login_time	(	PurpleAccount *	account,
		time_t	login_time
	)

Notifies Purple of our account's log-in time.

This is meant to be called from protocol plugins.

Parameters

account	The account the user is on.
login_time	The user's log-in time.

◆ purple_prpl_got_account_status()

void purple_prpl_got_account_status	(	PurpleAccount *	account,
		const char *	status_id,
			...
	)

Notifies Purple that our account's status has changed.

This is meant to be called from protocol plugins.

Parameters

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.

◆ purple_prpl_got_attention()

void purple_prpl_got_attention	(	PurpleConnection *	gc,
		const char *	who,
		guint	type_code
	)

Process an incoming attention message.

Parameters

gc	The connection that received the attention message.
who	Who requested your attention.
type_code	An index into the prpl's attention_types list determining the type of the attention request command to send.

Since: 2.5.0

◆ purple_prpl_got_attention_in_chat()

void purple_prpl_got_attention_in_chat	(	PurpleConnection *	gc,
		int	id,
		const char *	who,
		guint	type_code
	)

Process an incoming attention message in a chat.

Parameters

gc	The connection that received the attention message.
id	The chat id.
who	Who requested your attention.
type_code	An index into the prpl's attention_types list determining the type of the attention request command to send.

Since: 2.5.0

◆ purple_prpl_got_media_caps()

void purple_prpl_got_media_caps	(	PurpleAccount *	account,
		const char *	who
	)

Signals that the prpl received capabilities for the given contact.

This function is intended to be used only by prpls.

Parameters

account	The account the user is on.
who	The name of the contact for which capabilities have been received.

Since: 2.7.0

◆ purple_prpl_got_user_idle()

void purple_prpl_got_user_idle	(	PurpleAccount *	account,
		const char *	name,
		gboolean	idle,
		time_t	idle_time
	)

Notifies Purple that a buddy's idle state and time have changed.

This is meant to be called from protocol plugins.

Parameters

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 PRPL does not know this value then it should pass 0.

◆ purple_prpl_got_user_login_time()

void purple_prpl_got_user_login_time	(	PurpleAccount *	account,
		const char *	name,
		time_t	login_time
	)

Notifies Purple of a buddy's log-in time.

This is meant to be called from protocol plugins.

Parameters

account	The account the user is on.
name	The name of the buddy.
login_time	The user's log-in time.

◆ purple_prpl_got_user_status()

void purple_prpl_got_user_status	(	PurpleAccount *	account,
		const char *	name,
		const char *	status_id,
			...
	)

Notifies Purple that a buddy's status has been activated.

This is meant to be called from protocol plugins.

Parameters

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.

◆ purple_prpl_got_user_status_deactive()

void purple_prpl_got_user_status_deactive	(	PurpleAccount *	account,
		const char *	name,
		const char *	status_id
	)

Notifies libpurple that a buddy's status has been deactivated.

This is meant to be called from protocol plugins.

Parameters

account	The account the user is on.
name	The name of the buddy.
status_id	The status ID.

◆ purple_prpl_initiate_media()

gboolean purple_prpl_initiate_media	(	PurpleAccount *	account,
		const char *	who,
		PurpleMediaSessionType	type
	)

Initiates a media session with the given contact.

Parameters

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.

Returns: TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)

◆ purple_prpl_send_attention()

void purple_prpl_send_attention	(	PurpleConnection *	gc,
		const char *	who,
		guint	type_code
	)

Send an attention request message.

Parameters

gc	The connection to send the message on.
who	Whose attention to request.
type_code	An index into the prpl's attention_types list determining the type of the attention request command to send. 0 if prpl only defines one, but protocols are allowed to define more.

Note that you can't send arbitrary PurpleAttentionType's, because there is only a fixed set of attention commands.

Since: 2.5.0

Data Structures

Typedefs

Functions

Basic Protocol Information <br>

Detailed Description

Macro Definition Documentation

◆ NO_BUDDY_ICONS

◆ PURPLE_IS_PROTOCOL_PLUGIN

◆ PURPLE_PLUGIN_PROTOCOL_INFO

◆ PURPLE_PROTOCOL_PLUGIN_HAS_FUNC

Typedef Documentation

◆ PurpleAttentionType

◆ PurpleBuddyIconSpec

◆ PurplePluginProtocolInfo

◆ PurpleThumbnailSpec

Enumeration Type Documentation

◆ PurpleIconScaleRules

◆ PurpleProtocolOptions

Function Documentation

◆ purple_attention_type_get_icon_name()

◆ purple_attention_type_get_incoming_desc()

◆ purple_attention_type_get_name()

◆ purple_attention_type_get_outgoing_desc()

◆ purple_attention_type_get_unlocalized_name()

◆ purple_attention_type_new()

◆ purple_attention_type_set_icon_name()

◆ purple_attention_type_set_incoming_desc()

◆ purple_attention_type_set_name()

◆ purple_attention_type_set_outgoing_desc()

◆ purple_attention_type_set_unlocalized_name()

◆ purple_find_prpl()

◆ purple_prpl_change_account_status()

◆ purple_prpl_get_media_caps()

◆ purple_prpl_get_statuses()

◆ purple_prpl_got_account_actions()

◆ purple_prpl_got_account_idle()

◆ purple_prpl_got_account_login_time()

◆ purple_prpl_got_account_status()

◆ purple_prpl_got_attention()

◆ purple_prpl_got_attention_in_chat()

◆ purple_prpl_got_media_caps()

◆ purple_prpl_got_user_idle()

◆ purple_prpl_got_user_login_time()

◆ purple_prpl_got_user_status()

◆ purple_prpl_got_user_status_deactive()

◆ purple_prpl_initiate_media()

◆ purple_prpl_send_attention()