prpl.h File Reference
libpurple

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"`

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

## Functions

Attention Type API
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. More...
void | purple_attention_type_set_name (PurpleAttentionType *type, const char *name)
| Sets the displayed name of the attention-demanding event. More...
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. More...
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. More...
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. More...
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. More...
const char * | purple_attention_type_get_name (const PurpleAttentionType *type)
| Get the attention type's name as displayed by the UI. More...
const char * | purple_attention_type_get_incoming_desc (const PurpleAttentionType *type)
| Get the attention type's description shown when the event is received. More...
const char * | purple_attention_type_get_outgoing_desc (const PurpleAttentionType *type)
| Get the attention type's description shown when the event is sent. More...
const char * | purple_attention_type_get_icon_name (const PurpleAttentionType *type)
| Get the attention type's icon name. More...
const char * | purple_attention_type_get_unlocalized_name (const PurpleAttentionType *type)
| Get the attention type's unlocalized name; this is useful for some UIs. More...
Protocol Plugin API
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. More...
void | purple_prpl_got_account_login_time (PurpleAccount *account, time_t login_time)
| Notifies Purple of our account's log-in time. More...
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. More...
void | purple_prpl_got_account_actions (PurpleAccount *account)
| Notifies Purple that our account's actions have changed. More...
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. More...
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. More...
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. More...
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. More...
void | purple_prpl_change_account_status (PurpleAccount *account, PurpleStatus *old_status, PurpleStatus *new_status)
| Informs the server that our account's status changed. More...
GList * | purple_prpl_get_statuses (PurpleAccount *account, PurplePresence *presence)
| Retrieves the list of stock status types from a prpl. More...
void | purple_prpl_send_attention (PurpleConnection *gc, const char *who, guint type_code)
| Send an attention request message. More...
void | purple_prpl_got_attention (PurpleConnection *gc, const char *who, guint type_code)
| Process an incoming attention message. More...
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. More...
PurpleMediaCaps | purple_prpl_get_media_caps (PurpleAccount *account, const char *who)
| Determines if the contact supports the given media session type. More...
gboolean | purple_prpl_initiate_media (PurpleAccount *account, const char *who, PurpleMediaSessionType type)
| Initiates a media session with the given contact. More...
void | purple_prpl_got_media_caps (PurpleAccount *account, const char *who)
| Signals that the prpl received capabilities for the given contact. More...
Protocol Plugin Subsystem API
PurplePlugin * | purple_find_prpl (const char *id)
| Finds a protocol plugin structure of the specified type. More...

## Basic Protocol Information

#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
}

| Protocol options. More...
typedef struct _PurpleBuddyIconSpec | PurpleBuddyIconSpec
| A description of a Buddy Icon specification. More...
typedef struct _PurpleThumbnailSpec | PurpleThumbnailSpec
| A description of a file transfer thumbnail specification. More...

## Detailed Description

Protocol Plugin functions.

Definition in file prpl.h.

## Macro Definition Documentation

#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)
_PurplePluginProtocolInfo
A protocol plugin information structure.
Definition: prpl.h:223

Definition at line 651 of file prpl.h.

## Typedef Documentation

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.

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.

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

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.

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. MSN and Yahoo notify 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

Definition at line 136 of file prpl.h.

## Function Documentation

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

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

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

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

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

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

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

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

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

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

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

PurplePlugin* purple_find_prpl | ( | const char * | id | ) |

Finds a protocol plugin structure of the specified type.

Parameters

  id | The protocol plugin;

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

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.

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

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

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.

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.

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.

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

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

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

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.

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.

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.

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.

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)

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

Since
  2.5.0