prpl.h File Reference

Protocol Plugin functions. More...

#include "blist.h"
#include "conversation.h"
#include "ft.h"
#include "imgstore.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
struct  proto_chat_entry
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

Functions

Attention Type API
PurpleAttentionTypepurple_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
void purple_prpl_got_account_idle (PurpleAccount *account, gboolean idle, time_t idle_time)
 Notifies Purple that an account's idle state and time have changed.
void purple_prpl_got_account_login_time (PurpleAccount *account, time_t login_time)
 Notifies Purple of an account's log-in time.
void purple_prpl_got_account_status (PurpleAccount *account, const char *status_id,...) G_GNUC_NULL_TERMINATED
 Notifies Purple that an account's status has changed.
void purple_prpl_got_user_idle (PurpleAccount *account, const char *name, gboolean idle, time_t idle_time)
 Notifies Purple that a user'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 user'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 user'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 user's status has been deactivated.
void purple_prpl_change_account_status (PurpleAccount *account, PurpleStatus *old_status, PurpleStatus *new_status)
 Informs the server that an 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.
Protocol Plugin Subsystem API
PurplePluginpurple_find_prpl (const char *id)
 Finds a protocol plugin structure of the specified type.

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
}
 Protocol options. More...
typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec
 A description of a Buddy Icon specification.


Detailed Description

Protocol Plugin functions.

Definition in file prpl.h.


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

Definition at line 454 of file prpl.h.


Typedef Documentation

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.

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.


Enumeration Type Documentation

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.

Protocol options.

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

Enumerator:
OPT_PROTO_UNIQUE_CHATNAME  Use a unique name, not an alias, for chat rooms.

XMPP lets you choose what name you want for chat. So it shouldn't be pulling the alias for when you're in chat; 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 when screenname is not given.

Gadu-Gadu doesn't need a screenname to register new account.

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

Definition at line 125 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 an 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).

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_idle ( PurpleAccount account,
gboolean  idle,
time_t  idle_time 
)

Notifies Purple that an 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 an 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 an 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_user_idle ( PurpleAccount account,
const char *  name,
gboolean  idle,
time_t  idle_time 
)

Notifies Purple that a user'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 screen name of the user.
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 user's log-in time.

This is meant to be called from protocol plugins.

Parameters:
account The account the user is on.
name The screen name of the user.
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 user's status has been activated.

This is meant to be called from protocol plugins.

Parameters:
account The account the user is on.
name The screen name of the user.
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 user's status has been deactivated.

This is meant to be called from protocol plugins.

Parameters:
account The account the user is on.
name The screen name of the user.
status_id The status ID.

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