_PurplePluginProtocolInfo Struct Reference

A protocol plugin information structure. More...

#include <prpl.h>

Collaboration diagram for _PurplePluginProtocolInfo:
Collaboration graph

Data Fields

PurpleProtocolOptions options
 Protocol options.
GList * user_splits
 A GList of PurpleAccountUserSplit.
GList * protocol_options
 A GList of PurpleAccountOption.
PurpleBuddyIconSpec icon_spec
 The icon spec.
const char *(* list_icon )(PurpleAccount *account, PurpleBuddy *buddy)
 Returns the base icon name for the given buddy and account.
const char *(* list_emblem )(PurpleBuddy *buddy)
 Fills the four char**'s with string identifiers for "emblems" that the UI will interpret and display as relevant.
char *(* status_text )(PurpleBuddy *buddy)
 Gets a short string representing this buddy's status.
void(* tooltip_text )(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full)
 Allows the prpl to add text to a buddy's tooltip.
GList *(* status_types )(PurpleAccount *account)
 Returns a list of PurpleStatusType which exist for this account; this must be implemented, and must add at least the offline and online states.
GList *(* blist_node_menu )(PurpleBlistNode *node)
 Returns a list of PurpleMenuAction structs, which represent extra actions to be shown in (for example) the right-click menu for node.
GList *(* chat_info )(PurpleConnection *)
 Returns a list of proto_chat_entry structs, which represent information required by the PRPL to join a chat.
GHashTable *(* chat_info_defaults )(PurpleConnection *, const char *chat_name)
 Returns a hashtable which maps proto_chat_entry struct identifiers to default options as strings based on chat_name.
void(* login )(PurpleAccount *)
 This must be implemented.
void(* close )(PurpleConnection *)
 This must be implemented.
int(* send_im )(PurpleConnection *, const char *who, const char *message, PurpleMessageFlags flags)
 This PRPL function should return a positive value on success.
void(* set_info )(PurpleConnection *, const char *info)
unsigned int(* send_typing )(PurpleConnection *, const char *name, PurpleTypingState state)
void(* get_info )(PurpleConnection *, const char *who)
 Should arrange for purple_notify_userinfo() to be called with who's user info.
void(* set_status )(PurpleAccount *account, PurpleStatus *status)
void(* set_idle )(PurpleConnection *, int idletime)
void(* change_passwd )(PurpleConnection *, const char *old_pass, const char *new_pass)
void(* add_buddy )(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group)
 Add a buddy to a group on the server.
void(* add_buddies )(PurpleConnection *, GList *buddies, GList *groups)
void(* remove_buddy )(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group)
void(* remove_buddies )(PurpleConnection *, GList *buddies, GList *groups)
void(* add_permit )(PurpleConnection *, const char *name)
void(* add_deny )(PurpleConnection *, const char *name)
void(* rem_permit )(PurpleConnection *, const char *name)
void(* rem_deny )(PurpleConnection *, const char *name)
void(* set_permit_deny )(PurpleConnection *)
void(* join_chat )(PurpleConnection *, GHashTable *components)
 Called when the user requests joining a chat.
void(* reject_chat )(PurpleConnection *, GHashTable *components)
 Called when the user refuses a chat invitation.
char *(* get_chat_name )(GHashTable *components)
 Returns a chat name based on the information in components.
void(* chat_invite )(PurpleConnection *, int id, const char *message, const char *who)
 Invite a user to join a chat.
void(* chat_leave )(PurpleConnection *, int id)
 Called when the user requests leaving a chat.
void(* chat_whisper )(PurpleConnection *, int id, const char *who, const char *message)
 Send a whisper to a user in a chat.
int(* chat_send )(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags)
 Send a message to a chat.
void(* keepalive )(PurpleConnection *)
 If implemented, this will be called regularly for this prpl's active connections.
void(* register_user )(PurpleAccount *)
 new user registration
void(* get_cb_info )(PurpleConnection *, int, const char *who)
void(* get_cb_away )(PurpleConnection *, int, const char *who)
void(* alias_buddy )(PurpleConnection *, const char *who, const char *alias)
 save/store buddy's alias on server list/roster
void(* group_buddy )(PurpleConnection *, const char *who, const char *old_group, const char *new_group)
 change a buddy's group on a server list/roster
void(* rename_group )(PurpleConnection *, const char *old_name, PurpleGroup *group, GList *moved_buddies)
 rename a group on a server list/roster
void(* buddy_free )(PurpleBuddy *)
void(* convo_closed )(PurpleConnection *, const char *who)
const char *(* normalize )(const PurpleAccount *, const char *who)
 Convert the username who to its canonical form.
void(* set_buddy_icon )(PurpleConnection *, PurpleStoredImage *img)
 Set the buddy icon for the given connection to img.
void(* remove_group )(PurpleConnection *gc, PurpleGroup *group)
char *(* get_cb_real_name )(PurpleConnection *gc, int id, const char *who)
 Gets the real name of a participant in a chat.
void(* set_chat_topic )(PurpleConnection *gc, int id, const char *topic)
PurpleChat *(* find_blist_chat )(PurpleAccount *account, const char *name)
PurpleRoomlist *(* roomlist_get_list )(PurpleConnection *gc)
void(* roomlist_cancel )(PurpleRoomlist *list)
void(* roomlist_expand_category )(PurpleRoomlist *list, PurpleRoomlistRoom *category)
gboolean(* can_receive_file )(PurpleConnection *, const char *who)
void(* send_file )(PurpleConnection *, const char *who, const char *filename)
PurpleXfer *(* new_xfer )(PurpleConnection *, const char *who)
gboolean(* offline_message )(const PurpleBuddy *buddy)
 Checks whether offline messages to buddy are supported.
PurpleWhiteboardPrplOpswhiteboard_prpl_ops
int(* send_raw )(PurpleConnection *gc, const char *buf, int len)
 For use in plugins that may understand the underlying protocol.
char *(* roomlist_room_serialize )(PurpleRoomlistRoom *room)
void(* unregister_user )(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data)
 Remove the user from the server.
gboolean(* send_attention )(PurpleConnection *gc, const char *username, guint type)
GList *(* get_attention_types )(PurpleAccount *acct)
unsigned long struct_size
 The size of the PurplePluginProtocolInfo.
GHashTable *(* get_account_text_table )(PurpleAccount *account)
 This allows protocols to specify additional strings to be used for various purposes.
gboolean(* initiate_media )(PurpleAccount *account, const char *who, PurpleMediaSessionType type)
 Initiate a media session with the given contact.
PurpleMediaCaps(* get_media_caps )(PurpleAccount *account, const char *who)
 Checks to see if the given contact supports the given type of media session.
PurpleMood *(* get_moods )(PurpleAccount *account)
 Returns an array of "PurpleMood"s, with the last one having "mood" set to NULL.
void(* set_public_alias )(PurpleConnection *gc, const char *alias, PurpleSetPublicAliasSuccessCallback success_cb, PurpleSetPublicAliasFailureCallback failure_cb)
 Set the user's "friendly name" (or alias or nickname or whatever term you want to call it) on the server.
void(* get_public_alias )(PurpleConnection *gc, PurpleGetPublicAliasSuccessCallback success_cb, PurpleGetPublicAliasFailureCallback failure_cb)
 Retrieve the user's "friendly name" as set on the server.
void(* add_buddy_with_invite )(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message)
 Add a buddy to a group on the server.
void(* add_buddies_with_invite )(PurpleConnection *pc, GList *buddies, GList *groups, const char *message)

Detailed Description

A protocol plugin information structure.

Every protocol plugin initializes this structure. It is the gateway between purple and the protocol plugin. Many of these callbacks can be NULL. If a callback must be implemented, it has a comment indicating so.

Definition at line 223 of file prpl.h.

Field Documentation

void(* _PurplePluginProtocolInfo::add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group)

Add a buddy to a group on the server.

This PRPL function may be called in situations in which the buddy is already in the specified group. If the protocol supports authorization and the user is not already authorized to see the status of buddy, add_buddy should request authorization.

Deprecated:
Since 2.8.0, add_buddy_with_invite is preferred.
See Also
add_buddy_with_invite

Definition at line 347 of file prpl.h.

void(* _PurplePluginProtocolInfo::add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message)

Add a buddy to a group on the server.

This PRPL function may be called in situations in which the buddy is already in the specified group. If the protocol supports authorization and the user is not already authorized to see the status of buddy, add_buddy should request authorization.

If authorization is required, then use the supplied invite message.

Since
2.8.0

Definition at line 647 of file prpl.h.

GList*(* _PurplePluginProtocolInfo::chat_info)(PurpleConnection *)

Returns a list of proto_chat_entry structs, which represent information required by the PRPL to join a chat.

libpurple will call join_chat along with the information filled by the user.

Returns
A list of proto_chat_entry structs

Definition at line 280 of file prpl.h.

GHashTable*(* _PurplePluginProtocolInfo::chat_info_defaults)(PurpleConnection *, const char *chat_name)

Returns a hashtable which maps proto_chat_entry struct identifiers to default options as strings based on chat_name.

The resulting hashtable should be created with g_hash_table_new_full(g_str_hash, g_str_equal, NULL, g_free);. Use get_chat_name if you instead need to extract a chat name from a hashtable.

Parameters
chat_nameThe chat name to be turned into components
Returns
Hashtable containing the information extracted from chat_name

Definition at line 292 of file prpl.h.

void(* _PurplePluginProtocolInfo::chat_invite)(PurpleConnection *, int id, const char *message, const char *who)

Invite a user to join a chat.

Parameters
idThe id of the chat to invite the user to.
messageA message displayed to the user when the invitation is received.
whoThe name of the user to send the invation to.

Definition at line 394 of file prpl.h.

void(* _PurplePluginProtocolInfo::chat_leave)(PurpleConnection *, int id)

Called when the user requests leaving a chat.

Parameters
idThe id of the chat to leave

Definition at line 401 of file prpl.h.

int(* _PurplePluginProtocolInfo::chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags)

Send a message to a chat.

This PRPL function should return a positive value on success. If the message is too big to be sent, return -E2BIG. If the account is not connected, return -ENOTCONN. If the PRPL is unable to send the message for another reason, return some other negative value. You can use one of the valid errno values, or just big something.

Parameters
idThe id of the chat to send the message to.
messageThe message to send to the chat.
flagsA bitwise OR of PurpleMessageFlags representing message flags.
Returns
A positive number or 0 in case of success, a negative error number in case of failure.

Definition at line 429 of file prpl.h.

void(* _PurplePluginProtocolInfo::chat_whisper)(PurpleConnection *, int id, const char *who, const char *message)

Send a whisper to a user in a chat.

Parameters
idThe id of the chat.
whoThe name of the user to send the whisper to.
messageThe message of the whisper.

Definition at line 410 of file prpl.h.

void(* _PurplePluginProtocolInfo::close)(PurpleConnection *)

This must be implemented.

Definition at line 300 of file prpl.h.

GHashTable*(* _PurplePluginProtocolInfo::get_account_text_table)(PurpleAccount *account)

This allows protocols to specify additional strings to be used for various purposes.

The idea is to stuff a bunch of strings in this hash table instead of expanding the struct for every addition. This hash table is allocated every call and MUST be unrefed by the caller.

Parameters
accountThe account to specify. This can be NULL.
Returns
The protocol's string hash table. The hash table should be destroyed by the caller when it's no longer needed.

Definition at line 566 of file prpl.h.

void(* _PurplePluginProtocolInfo::get_cb_away)(PurpleConnection *, int, const char *who)
void(* _PurplePluginProtocolInfo::get_cb_info)(PurpleConnection *, int, const char *who)
Deprecated:
Use PurplePluginProtocolInfo.get_info instead.

Definition at line 445 of file prpl.h.

char*(* _PurplePluginProtocolInfo::get_cb_real_name)(PurpleConnection *gc, int id, const char *who)

Gets the real name of a participant in a chat.

For example, on XMPP this turns a chat room nick foo into room@server/foo

Parameters
gcthe connection on which the room is.
idthe ID of the chat room.
whothe nickname of the chat participant.
Returns
the real name of the participant. This string must be freed by the caller.

Definition at line 493 of file prpl.h.

char*(* _PurplePluginProtocolInfo::get_chat_name)(GHashTable *components)

Returns a chat name based on the information in components.

Use chat_info_defaults if you instead need to generate a hashtable from a chat name.

Parameters
componentsA hashtable containing information about the chat.

Definition at line 384 of file prpl.h.

PurpleMediaCaps(* _PurplePluginProtocolInfo::get_media_caps)(PurpleAccount *account, const char *who)

Checks to see if the given contact supports the given type of media session.

Parameters
accountThe account the contact is on.
whoThe remote user to check for media capability with.
Returns
The media caps the contact supports.

Definition at line 586 of file prpl.h.

PurpleMood*(* _PurplePluginProtocolInfo::get_moods)(PurpleAccount *account)

Returns an array of "PurpleMood"s, with the last one having "mood" set to NULL.

Since
2.7.0

Definition at line 594 of file prpl.h.

void(* _PurplePluginProtocolInfo::get_public_alias)(PurpleConnection *gc, PurpleGetPublicAliasSuccessCallback success_cb, PurpleGetPublicAliasFailureCallback failure_cb)

Retrieve the user's "friendly name" as set on the server.

The protocol plugin should call success_cb or failure_cb asynchronously (even if it knows immediately that the get will fail, call one of the callbacks from an idle/0-second timeout) depending on if the nickname is retrieved.

Parameters
gcThe connection for which to retireve the alias
success_cbCallback to be called with the retrieved alias
failure_cbCallback to be called if the prpl is unable to retrieve the alias
See Also
purple_account_get_public_alias
Since
2.7.0

Definition at line 631 of file prpl.h.

PurpleBuddyIconSpec _PurplePluginProtocolInfo::icon_spec

The icon spec.

Definition at line 230 of file prpl.h.

gboolean(* _PurplePluginProtocolInfo::initiate_media)(PurpleAccount *account, const char *who, PurpleMediaSessionType type)

Initiate a media session with the given contact.

Parameters
accountThe account to initiate the media session on.
whoThe remote user to initiate the session with.
typeThe type of media session to initiate.
Returns
TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)

Definition at line 576 of file prpl.h.

void(* _PurplePluginProtocolInfo::join_chat)(PurpleConnection *, GHashTable *components)

Called when the user requests joining a chat.

Should arrange for serv_got_joined_chat to be called.

Parameters
componentsA hashtable containing information required to join the chat as described by the entries returned by chat_info. It may also be called when accepting an invitation, in which case this matches the data parameter passed to serv_got_chat_invite.

Definition at line 367 of file prpl.h.

void(* _PurplePluginProtocolInfo::keepalive)(PurpleConnection *)

If implemented, this will be called regularly for this prpl's active connections.

You'd want to do this if you need to repeatedly send some kind of keepalive packet to the server to avoid being disconnected. ("Regularly" is defined by KEEPALIVE_INTERVAL in libpurple/connection.c.)

Definition at line 437 of file prpl.h.

const char*(* _PurplePluginProtocolInfo::list_icon)(PurpleAccount *account, PurpleBuddy *buddy)

Returns the base icon name for the given buddy and account.

If buddy is NULL and the account is non-NULL, it will return the name to use for the account's icon. If both are NULL, it will return the name to use for the protocol's icon.

This must be implemented.

Definition at line 240 of file prpl.h.

void(* _PurplePluginProtocolInfo::login)(PurpleAccount *)

This must be implemented.

Definition at line 297 of file prpl.h.

const char*(* _PurplePluginProtocolInfo::normalize)(const PurpleAccount *, const char *who)

Convert the username who to its canonical form.

(For example, AIM treats "fOo BaR" and "foobar" as the same user; this function should return the same normalized string for both of those.)

Definition at line 473 of file prpl.h.

gboolean(* _PurplePluginProtocolInfo::offline_message)(const PurpleBuddy *buddy)

Checks whether offline messages to buddy are supported.

Returns
TRUE if buddy can be sent messages while they are offline, or FALSE if not.

Definition at line 513 of file prpl.h.

PurpleProtocolOptions _PurplePluginProtocolInfo::options

Protocol options.

Definition at line 225 of file prpl.h.

void(* _PurplePluginProtocolInfo::reject_chat)(PurpleConnection *, GHashTable *components)

Called when the user refuses a chat invitation.

Parameters
componentsA hashtable containing information required to join the chat as passed to serv_got_chat_invite.

Definition at line 375 of file prpl.h.

int(* _PurplePluginProtocolInfo::send_im)(PurpleConnection *, const char *who, const char *message, PurpleMessageFlags flags)

This PRPL function should return a positive value on success.

If the message is too big to be sent, return -E2BIG. If the account is not connected, return -ENOTCONN. If the PRPL is unable to send the message for another reason, return some other negative value. You can use one of the valid errno values, or just big something. If the message should not be echoed to the conversation window, return 0.

Definition at line 311 of file prpl.h.

unsigned int(* _PurplePluginProtocolInfo::send_typing)(PurpleConnection *, const char *name, PurpleTypingState state)
Returns
If this protocol requires the PURPLE_TYPING message to be sent repeatedly to signify that the user is still typing, then the PRPL should return the number of seconds to wait before sending a subsequent notification. Otherwise the PRPL should return 0.

Definition at line 324 of file prpl.h.

void(* _PurplePluginProtocolInfo::set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img)

Set the buddy icon for the given connection to img.

The prpl does NOT own a reference to img; if it needs one, it must purple_imgstore_ref(img) itself.

Definition at line 480 of file prpl.h.

void(* _PurplePluginProtocolInfo::set_public_alias)(PurpleConnection *gc, const char *alias, PurpleSetPublicAliasSuccessCallback success_cb, PurpleSetPublicAliasFailureCallback failure_cb)

Set the user's "friendly name" (or alias or nickname or whatever term you want to call it) on the server.

The protocol plugin should call success_cb or failure_cb asynchronously (if it knows immediately that the set will fail, call one of the callbacks from an idle/0-second timeout) depending on if the nickname is set successfully.

Parameters
gcThe connection for which to set an alias
aliasThe new server-side alias/nickname for this account, or NULL to unset the alias/nickname (or return it to a protocol-specific "default").
success_cbCallback to be called if the public alias is set
failure_cbCallback to be called if setting the public alias fails
See Also
purple_account_set_public_alias
Since
2.7.0

Definition at line 614 of file prpl.h.

char*(* _PurplePluginProtocolInfo::status_text)(PurpleBuddy *buddy)

Gets a short string representing this buddy's status.

This will be shown on the buddy list.

Definition at line 252 of file prpl.h.

unsigned long _PurplePluginProtocolInfo::struct_size

The size of the PurplePluginProtocolInfo.

This should always be sizeof(PurplePluginProtocolInfo). This allows adding more functions to this struct without requiring a major version bump.

Definition at line 540 of file prpl.h.

void(* _PurplePluginProtocolInfo::unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data)

Remove the user from the server.

The account can either be connected or disconnected. After the removal is finished, the connection will stay open and has to be closed!

Definition at line 530 of file prpl.h.


The documentation for this struct was generated from the following file:
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!