1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/prpl.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,838 @@
1.4 +/**
1.5 + * @file prpl.h Protocol Plugin functions
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +
1.30 +/* this file should be all that prpls need to include. therefore, by including
1.31 + * this file, they should get glib, proxy, purple_connection, prpl, etc. */
1.32 +
1.33 +#ifndef _PURPLE_PRPL_H_
1.34 +#define _PURPLE_PRPL_H_
1.35 +
1.36 +typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
1.37 +/** @copydoc _PurpleAttentionType */
1.38 +typedef struct _PurpleAttentionType PurpleAttentionType;
1.39 +
1.40 +/**************************************************************************/
1.41 +/** @name Basic Protocol Information */
1.42 +/**************************************************************************/
1.43 +
1.44 +typedef enum {
1.45 + PURPLE_ICON_SCALE_DISPLAY = 0x01, /**< We scale the icon when we display it */
1.46 + PURPLE_ICON_SCALE_SEND = 0x02 /**< We scale the icon before we send it to the server */
1.47 +} PurpleIconScaleRules;
1.48 +
1.49 +
1.50 +/**
1.51 + * A description of a Buddy Icon specification. This tells Purple what kind of image file
1.52 + * it should give this prpl, and what kind of image file it should expect back.
1.53 + * Dimensions less than 1 should be ignored and the image not scaled.
1.54 + */
1.55 +typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
1.56 +
1.57 +/**
1.58 + * This \#define exists just to make it easier to fill out the buddy icon
1.59 + * field in the prpl info struct for protocols that couldn't care less.
1.60 + */
1.61 +#define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
1.62 +
1.63 +#ifdef HAVE_UNISTD_H
1.64 +#include <unistd.h>
1.65 +#endif
1.66 +
1.67 +#include "blist.h"
1.68 +#include "conversation.h"
1.69 +#include "ft.h"
1.70 +#include "imgstore.h"
1.71 +#include "media.h"
1.72 +#include "notify.h"
1.73 +#include "proxy.h"
1.74 +#include "plugin.h"
1.75 +#include "roomlist.h"
1.76 +#include "status.h"
1.77 +#include "whiteboard.h"
1.78 +
1.79 +
1.80 +/** @copydoc PurpleBuddyIconSpec */
1.81 +struct _PurpleBuddyIconSpec {
1.82 + /** This is a comma-delimited list of image formats or @c NULL if icons
1.83 + * are not supported. Neither the core nor the prpl will actually
1.84 + * check to see if the data it's given matches this; it's entirely up
1.85 + * to the UI to do what it wants
1.86 + */
1.87 + char *format;
1.88 +
1.89 + int min_width; /**< Minimum width of this icon */
1.90 + int min_height; /**< Minimum height of this icon */
1.91 + int max_width; /**< Maximum width of this icon */
1.92 + int max_height; /**< Maximum height of this icon */
1.93 + size_t max_filesize; /**< Maximum size in bytes */
1.94 + PurpleIconScaleRules scale_rules; /**< How to stretch this icon */
1.95 +};
1.96 +
1.97 +struct proto_chat_entry {
1.98 + const char *label;
1.99 + const char *identifier;
1.100 + gboolean required;
1.101 + gboolean is_int;
1.102 + int min;
1.103 + int max;
1.104 + gboolean secret;
1.105 +};
1.106 +
1.107 +/** Represents "nudges" and "buzzes" that you may send to a buddy to attract
1.108 + * their attention (or vice-versa).
1.109 + */
1.110 +struct _PurpleAttentionType
1.111 +{
1.112 + const char *name; /**< Shown in GUI elements */
1.113 + const char *incoming_description; /**< Shown when sent */
1.114 + const char *outgoing_description; /**< Shown when receied */
1.115 + const char *icon_name; /**< Icon to display (optional) */
1.116 + const char *unlocalized_name; /**< Unlocalized name for UIs needing it */
1.117 +
1.118 + /* Reserved fields for future purposes */
1.119 + gpointer _reserved2;
1.120 + gpointer _reserved3;
1.121 + gpointer _reserved4;
1.122 +};
1.123 +
1.124 +/**
1.125 + * Protocol options
1.126 + *
1.127 + * These should all be stuff that some plugins can do and others can't.
1.128 + */
1.129 +typedef enum
1.130 +{
1.131 + /**
1.132 + * User names are unique to a chat and are not shared between rooms.
1.133 + *
1.134 + * XMPP lets you choose what name you want in chats, so it shouldn't
1.135 + * be pulling the aliases from the buddy list for the chat list;
1.136 + * it gets annoying.
1.137 + */
1.138 + OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
1.139 +
1.140 + /**
1.141 + * Chat rooms have topics.
1.142 + *
1.143 + * IRC and XMPP support this.
1.144 + */
1.145 + OPT_PROTO_CHAT_TOPIC = 0x00000008,
1.146 +
1.147 + /**
1.148 + * Don't require passwords for sign-in.
1.149 + *
1.150 + * Zephyr doesn't require passwords, so there's no
1.151 + * need for a password prompt.
1.152 + */
1.153 + OPT_PROTO_NO_PASSWORD = 0x00000010,
1.154 +
1.155 + /**
1.156 + * Notify on new mail.
1.157 + *
1.158 + * MSN and Yahoo notify you when you have new mail.
1.159 + */
1.160 + OPT_PROTO_MAIL_CHECK = 0x00000020,
1.161 +
1.162 + /**
1.163 + * Images in IMs.
1.164 + *
1.165 + * Oscar lets you send images in direct IMs.
1.166 + */
1.167 + OPT_PROTO_IM_IMAGE = 0x00000040,
1.168 +
1.169 + /**
1.170 + * Allow passwords to be optional.
1.171 + *
1.172 + * Passwords in IRC are optional, and are needed for certain
1.173 + * functionality.
1.174 + */
1.175 + OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
1.176 +
1.177 + /**
1.178 + * Allows font size to be specified in sane point size
1.179 + *
1.180 + * Probably just XMPP and Y!M
1.181 + */
1.182 + OPT_PROTO_USE_POINTSIZE = 0x00000100,
1.183 +
1.184 + /**
1.185 + * Set the Register button active even when the username has not
1.186 + * been specified.
1.187 + *
1.188 + * Gadu-Gadu doesn't need a username to register new account (because
1.189 + * usernames are assigned by the server).
1.190 + */
1.191 + OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
1.192 +
1.193 + /**
1.194 + * Indicates that slash commands are native to this protocol.
1.195 + * Used as a hint that unknown commands should not be sent as messages.
1.196 + * @since 2.1.0
1.197 + */
1.198 + OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400
1.199 +
1.200 +} PurpleProtocolOptions;
1.201 +
1.202 +/**
1.203 + * A protocol plugin information structure.
1.204 + *
1.205 + * Every protocol plugin initializes this structure. It is the gateway
1.206 + * between purple and the protocol plugin. Many of these callbacks can be
1.207 + * NULL. If a callback must be implemented, it has a comment indicating so.
1.208 + */
1.209 +struct _PurplePluginProtocolInfo
1.210 +{
1.211 + PurpleProtocolOptions options; /**< Protocol options. */
1.212 +
1.213 + GList *user_splits; /**< A GList of PurpleAccountUserSplit */
1.214 + GList *protocol_options; /**< A GList of PurpleAccountOption */
1.215 +
1.216 + PurpleBuddyIconSpec icon_spec; /**< The icon spec. */
1.217 +
1.218 + /**
1.219 + * Returns the base icon name for the given buddy and account.
1.220 + * If buddy is NULL and the account is non-NULL, it will return the
1.221 + * name to use for the account's icon. If both are NULL, it will
1.222 + * return the name to use for the protocol's icon.
1.223 + *
1.224 + * This must be implemented.
1.225 + */
1.226 + const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
1.227 +
1.228 + /**
1.229 + * Fills the four char**'s with string identifiers for "emblems"
1.230 + * that the UI will interpret and display as relevant
1.231 + */
1.232 + const char *(*list_emblem)(PurpleBuddy *buddy);
1.233 +
1.234 + /**
1.235 + * Gets a short string representing this buddy's status. This will
1.236 + * be shown on the buddy list.
1.237 + */
1.238 + char *(*status_text)(PurpleBuddy *buddy);
1.239 +
1.240 + /**
1.241 + * Allows the prpl to add text to a buddy's tooltip.
1.242 + */
1.243 + void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
1.244 +
1.245 + /**
1.246 + * Returns a list of #PurpleStatusType which exist for this account;
1.247 + * this must be implemented, and must add at least the offline and
1.248 + * online states.
1.249 + */
1.250 + GList *(*status_types)(PurpleAccount *account);
1.251 +
1.252 + /**
1.253 + * Returns a list of #PurpleMenuAction structs, which represent extra
1.254 + * actions to be shown in (for example) the right-click menu for @a
1.255 + * node.
1.256 + */
1.257 + GList *(*blist_node_menu)(PurpleBlistNode *node);
1.258 + GList *(*chat_info)(PurpleConnection *);
1.259 + GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
1.260 +
1.261 + /* All the server-related functions */
1.262 +
1.263 + /** This must be implemented. */
1.264 + void (*login)(PurpleAccount *);
1.265 +
1.266 + /** This must be implemented. */
1.267 + void (*close)(PurpleConnection *);
1.268 +
1.269 + /**
1.270 + * This PRPL function should return a positive value on success.
1.271 + * If the message is too big to be sent, return -E2BIG. If
1.272 + * the account is not connected, return -ENOTCONN. If the
1.273 + * PRPL is unable to send the message for another reason, return
1.274 + * some other negative value. You can use one of the valid
1.275 + * errno values, or just big something. If the message should
1.276 + * not be echoed to the conversation window, return 0.
1.277 + */
1.278 + int (*send_im)(PurpleConnection *, const char *who,
1.279 + const char *message,
1.280 + PurpleMessageFlags flags);
1.281 +
1.282 + void (*set_info)(PurpleConnection *, const char *info);
1.283 +
1.284 + /**
1.285 + * @return If this protocol requires the PURPLE_TYPING message to
1.286 + * be sent repeatedly to signify that the user is still
1.287 + * typing, then the PRPL should return the number of
1.288 + * seconds to wait before sending a subsequent notification.
1.289 + * Otherwise the PRPL should return 0.
1.290 + */
1.291 + unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
1.292 +
1.293 + /**
1.294 + * Should arrange for purple_notify_userinfo() to be called with
1.295 + * @a who's user info.
1.296 + */
1.297 + void (*get_info)(PurpleConnection *, const char *who);
1.298 + void (*set_status)(PurpleAccount *account, PurpleStatus *status);
1.299 +
1.300 + void (*set_idle)(PurpleConnection *, int idletime);
1.301 + void (*change_passwd)(PurpleConnection *, const char *old_pass,
1.302 + const char *new_pass);
1.303 + /**
1.304 + * Add a buddy to a group on the server.
1.305 + *
1.306 + * This PRPL function may be called in situations in which the buddy is
1.307 + * already in the specified group. If the protocol supports
1.308 + * authorization and the user is not already authorized to see the
1.309 + * status of \a buddy, \a add_buddy should request authorization.
1.310 + */
1.311 + void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
1.312 + void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
1.313 + void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
1.314 + void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
1.315 + void (*add_permit)(PurpleConnection *, const char *name);
1.316 + void (*add_deny)(PurpleConnection *, const char *name);
1.317 + void (*rem_permit)(PurpleConnection *, const char *name);
1.318 + void (*rem_deny)(PurpleConnection *, const char *name);
1.319 + void (*set_permit_deny)(PurpleConnection *);
1.320 + void (*join_chat)(PurpleConnection *, GHashTable *components);
1.321 + void (*reject_chat)(PurpleConnection *, GHashTable *components);
1.322 + char *(*get_chat_name)(GHashTable *components);
1.323 + void (*chat_invite)(PurpleConnection *, int id,
1.324 + const char *message, const char *who);
1.325 + void (*chat_leave)(PurpleConnection *, int id);
1.326 + void (*chat_whisper)(PurpleConnection *, int id,
1.327 + const char *who, const char *message);
1.328 + int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
1.329 +
1.330 + /** If implemented, this will be called regularly for this prpl's
1.331 + * active connections. You'd want to do this if you need to repeatedly
1.332 + * send some kind of keepalive packet to the server to avoid being
1.333 + * disconnected. ("Regularly" is defined by
1.334 + * <code>KEEPALIVE_INTERVAL</code> in <tt>libpurple/connection.c</tt>.)
1.335 + */
1.336 + void (*keepalive)(PurpleConnection *);
1.337 +
1.338 + /** new user registration */
1.339 + void (*register_user)(PurpleAccount *);
1.340 +
1.341 + /**
1.342 + * @deprecated Use #PurplePluginProtocolInfo.get_info instead.
1.343 + */
1.344 + void (*get_cb_info)(PurpleConnection *, int, const char *who);
1.345 + /**
1.346 + * @deprecated Use #PurplePluginProtocolInfo.get_cb_real_name and
1.347 + * #PurplePluginProtocolInfo.status_text instead.
1.348 + */
1.349 + void (*get_cb_away)(PurpleConnection *, int, const char *who);
1.350 +
1.351 + /** save/store buddy's alias on server list/roster */
1.352 + void (*alias_buddy)(PurpleConnection *, const char *who,
1.353 + const char *alias);
1.354 +
1.355 + /** change a buddy's group on a server list/roster */
1.356 + void (*group_buddy)(PurpleConnection *, const char *who,
1.357 + const char *old_group, const char *new_group);
1.358 +
1.359 + /** rename a group on a server list/roster */
1.360 + void (*rename_group)(PurpleConnection *, const char *old_name,
1.361 + PurpleGroup *group, GList *moved_buddies);
1.362 +
1.363 + void (*buddy_free)(PurpleBuddy *);
1.364 +
1.365 + void (*convo_closed)(PurpleConnection *, const char *who);
1.366 +
1.367 + /**
1.368 + * Convert the username @a who to its canonical form. (For example,
1.369 + * AIM treats "fOo BaR" and "foobar" as the same user; this function
1.370 + * should return the same normalized string for both of those.)
1.371 + */
1.372 + const char *(*normalize)(const PurpleAccount *, const char *who);
1.373 +
1.374 + /**
1.375 + * Set the buddy icon for the given connection to @a img. The prpl
1.376 + * does NOT own a reference to @a img; if it needs one, it must
1.377 + * #purple_imgstore_ref(@a img) itself.
1.378 + */
1.379 + void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
1.380 +
1.381 + void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
1.382 +
1.383 + /** Gets the real name of a participant in a chat. For example, on
1.384 + * XMPP this turns a chat room nick <tt>foo</tt> into
1.385 + * <tt>room\@server/foo</tt>
1.386 + * @param gc the connection on which the room is.
1.387 + * @param id the ID of the chat room.
1.388 + * @param who the nickname of the chat participant.
1.389 + * @return the real name of the participant. This string must be
1.390 + * freed by the caller.
1.391 + */
1.392 + char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
1.393 +
1.394 + void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
1.395 +
1.396 + PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
1.397 +
1.398 + /* room listing prpl callbacks */
1.399 + PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
1.400 + void (*roomlist_cancel)(PurpleRoomlist *list);
1.401 + void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
1.402 +
1.403 + /* file transfer callbacks */
1.404 + gboolean (*can_receive_file)(PurpleConnection *, const char *who);
1.405 + void (*send_file)(PurpleConnection *, const char *who, const char *filename);
1.406 + PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
1.407 +
1.408 + /** Checks whether offline messages to @a buddy are supported.
1.409 + * @return @c TRUE if @a buddy can be sent messages while they are
1.410 + * offline, or @c FALSE if not.
1.411 + */
1.412 + gboolean (*offline_message)(const PurpleBuddy *buddy);
1.413 +
1.414 + PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
1.415 +
1.416 + /** For use in plugins that may understand the underlying protocol */
1.417 + int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
1.418 +
1.419 + /* room list serialize */
1.420 + char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
1.421 +
1.422 + /** Remove the user from the server. The account can either be
1.423 + * connected or disconnected. After the removal is finished, the
1.424 + * connection will stay open and has to be closed!
1.425 + */
1.426 + /* This is here rather than next to register_user for API compatibility
1.427 + * reasons.
1.428 + */
1.429 + void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
1.430 +
1.431 + /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
1.432 + gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
1.433 + GList *(*get_attention_types)(PurpleAccount *acct);
1.434 +
1.435 + /**
1.436 + * The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
1.437 + * This allows adding more functions to this struct without requiring a major version bump.
1.438 + */
1.439 + unsigned long struct_size;
1.440 +
1.441 + /* NOTE:
1.442 + * If more functions are added, they should accessed using the following syntax:
1.443 + *
1.444 + * if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
1.445 + * prpl->new_function(...);
1.446 + *
1.447 + * instead of
1.448 + *
1.449 + * if (prpl->new_function != NULL)
1.450 + * prpl->new_function(...);
1.451 + *
1.452 + * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
1.453 + * functions (e.g. login, send_im etc.) too.
1.454 + */
1.455 +
1.456 + /** This allows protocols to specify additional strings to be used for
1.457 + * various purposes. The idea is to stuff a bunch of strings in this hash
1.458 + * table instead of expanding the struct for every addition. This hash
1.459 + * table is allocated every call and MUST be unrefed by the caller.
1.460 + *
1.461 + * @param account The account to specify. This can be NULL.
1.462 + * @return The protocol's string hash table. The hash table should be
1.463 + * destroyed by the caller when it's no longer needed.
1.464 + */
1.465 + GHashTable *(*get_account_text_table)(PurpleAccount *account);
1.466 +
1.467 + /**
1.468 + * Initiate a media session with the given contact.
1.469 + *
1.470 + * @param account The account to initiate the media session on.
1.471 + * @param who The remote user to initiate the session with.
1.472 + * @param type The type of media session to initiate.
1.473 + * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
1.474 + */
1.475 + gboolean (*initiate_media)(PurpleAccount *account, const char *who,
1.476 + PurpleMediaSessionType type);
1.477 +
1.478 + /**
1.479 + * Checks to see if the given contact supports the given type of media session.
1.480 + *
1.481 + * @param account The account the contact is on.
1.482 + * @param who The remote user to check for media capability with.
1.483 + * @return The media caps the contact supports.
1.484 + */
1.485 + PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
1.486 + const char *who);
1.487 +};
1.488 +
1.489 +#define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
1.490 + (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
1.491 + || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
1.492 + prpl->member != NULL)
1.493 +
1.494 +
1.495 +#define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
1.496 + ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
1.497 +
1.498 +#define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
1.499 + ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
1.500 +
1.501 +#ifdef __cplusplus
1.502 +extern "C" {
1.503 +#endif
1.504 +
1.505 +/**************************************************************************/
1.506 +/** @name Attention Type API */
1.507 +/**************************************************************************/
1.508 +/*@{*/
1.509 +
1.510 +/**
1.511 + * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
1.512 + *
1.513 + * @param ulname A non-localized string that can be used by UIs in need of such
1.514 + * non-localized strings. This should be the same as @a name,
1.515 + * without localization.
1.516 + * @param name A localized string that the UI may display for the event. This
1.517 + * should be the same string as @a ulname, with localization.
1.518 + * @param inc_desc A localized description shown when the event is received.
1.519 + * @param out_desc A localized description shown when the event is sent.
1.520 + * @return A pointer to the new object.
1.521 + * @since 2.4.0
1.522 + */
1.523 +PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
1.524 + const char *inc_desc, const char *out_desc);
1.525 +
1.526 +/**
1.527 + * Sets the displayed name of the attention-demanding event.
1.528 + *
1.529 + * @param type The attention type.
1.530 + * @param name The localized name that will be displayed by UIs. This should be
1.531 + * the same string given as the unlocalized name, but with
1.532 + * localization.
1.533 + * @since 2.4.0
1.534 + */
1.535 +void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
1.536 +
1.537 +/**
1.538 + * Sets the description of the attention-demanding event shown in conversations
1.539 + * when the event is received.
1.540 + *
1.541 + * @param type The attention type.
1.542 + * @param desc The localized description for incoming events.
1.543 + * @since 2.4.0
1.544 + */
1.545 +void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
1.546 +
1.547 +/**
1.548 + * Sets the description of the attention-demanding event shown in conversations
1.549 + * when the event is sent.
1.550 + *
1.551 + * @param type The attention type.
1.552 + * @param desc The localized description for outgoing events.
1.553 + * @since 2.4.0
1.554 + */
1.555 +void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
1.556 +
1.557 +/**
1.558 + * Sets the name of the icon to display for the attention event; this is optional.
1.559 + *
1.560 + * @param type The attention type.
1.561 + * @param name The icon's name.
1.562 + * @note Icons are optional for attention events.
1.563 + * @since 2.4.0
1.564 + */
1.565 +void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
1.566 +
1.567 +/**
1.568 + * Sets the unlocalized name of the attention event; some UIs may need this,
1.569 + * thus it is required.
1.570 + *
1.571 + * @param type The attention type.
1.572 + * @param ulname The unlocalized name. This should be the same string given as
1.573 + * the localized name, but without localization.
1.574 + * @since 2.4.0
1.575 + */
1.576 +void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
1.577 +
1.578 +/**
1.579 + * Get the attention type's name as displayed by the UI.
1.580 + *
1.581 + * @param type The attention type.
1.582 + * @return The name.
1.583 + * @since 2.4.0
1.584 + */
1.585 +const char *purple_attention_type_get_name(const PurpleAttentionType *type);
1.586 +
1.587 +/**
1.588 + * Get the attention type's description shown when the event is received.
1.589 + *
1.590 + * @param type The attention type.
1.591 + * @return The description.
1.592 + * @since 2.4.0
1.593 + */
1.594 +const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
1.595 +
1.596 +/**
1.597 + * Get the attention type's description shown when the event is sent.
1.598 + *
1.599 + * @param type The attention type.
1.600 + * @return The description.
1.601 + * @since 2.4.0
1.602 + */
1.603 +const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
1.604 +
1.605 +/**
1.606 + * Get the attention type's icon name.
1.607 + *
1.608 + * @param type The attention type.
1.609 + * @return The icon name or @c NULL if unset/empty.
1.610 + * @note Icons are optional for attention events.
1.611 + * @since 2.4.0
1.612 + */
1.613 +const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
1.614 +
1.615 +/**
1.616 + * Get the attention type's unlocalized name; this is useful for some UIs.
1.617 + *
1.618 + * @param type The attention type
1.619 + * @return The unlocalized name.
1.620 + * @since 2.4.0
1.621 + */
1.622 +const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
1.623 +
1.624 +/*@}*/
1.625 +
1.626 +/**************************************************************************/
1.627 +/** @name Protocol Plugin API */
1.628 +/**************************************************************************/
1.629 +/*@{*/
1.630 +
1.631 +/**
1.632 + * Notifies Purple that our account's idle state and time have changed.
1.633 + *
1.634 + * This is meant to be called from protocol plugins.
1.635 + *
1.636 + * @param account The account.
1.637 + * @param idle The user's idle state.
1.638 + * @param idle_time The user's idle time.
1.639 + */
1.640 +void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
1.641 + time_t idle_time);
1.642 +
1.643 +/**
1.644 + * Notifies Purple of our account's log-in time.
1.645 + *
1.646 + * This is meant to be called from protocol plugins.
1.647 + *
1.648 + * @param account The account the user is on.
1.649 + * @param login_time The user's log-in time.
1.650 + */
1.651 +void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
1.652 +
1.653 +/**
1.654 + * Notifies Purple that our account's status has changed.
1.655 + *
1.656 + * This is meant to be called from protocol plugins.
1.657 + *
1.658 + * @param account The account the user is on.
1.659 + * @param status_id The status ID.
1.660 + * @param ... A NULL-terminated list of attribute IDs and values,
1.661 + * beginning with the value for @a attr_id.
1.662 + */
1.663 +void purple_prpl_got_account_status(PurpleAccount *account,
1.664 + const char *status_id, ...) G_GNUC_NULL_TERMINATED;
1.665 +
1.666 +/**
1.667 + * Notifies Purple that our account's actions have changed. This is only
1.668 + * called after the initial connection. Emits the account-actions-changed
1.669 + * signal.
1.670 + *
1.671 + * This is meant to be called from protocol plugins.
1.672 + *
1.673 + * @param account The account.
1.674 + *
1.675 + * @see account-actions-changed
1.676 + * @since 2.6.0
1.677 + */
1.678 +void purple_prpl_got_account_actions(PurpleAccount *account);
1.679 +
1.680 +/**
1.681 + * Notifies Purple that a buddy's idle state and time have changed.
1.682 + *
1.683 + * This is meant to be called from protocol plugins.
1.684 + *
1.685 + * @param account The account the user is on.
1.686 + * @param name The name of the buddy.
1.687 + * @param idle The user's idle state.
1.688 + * @param idle_time The user's idle time. This is the time at
1.689 + * which the user became idle, in seconds since
1.690 + * the epoch. If the PRPL does not know this value
1.691 + * then it should pass 0.
1.692 + */
1.693 +void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
1.694 + gboolean idle, time_t idle_time);
1.695 +
1.696 +/**
1.697 + * Notifies Purple of a buddy's log-in time.
1.698 + *
1.699 + * This is meant to be called from protocol plugins.
1.700 + *
1.701 + * @param account The account the user is on.
1.702 + * @param name The name of the buddy.
1.703 + * @param login_time The user's log-in time.
1.704 + */
1.705 +void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
1.706 + time_t login_time);
1.707 +
1.708 +/**
1.709 + * Notifies Purple that a buddy's status has been activated.
1.710 + *
1.711 + * This is meant to be called from protocol plugins.
1.712 + *
1.713 + * @param account The account the user is on.
1.714 + * @param name The name of the buddy.
1.715 + * @param status_id The status ID.
1.716 + * @param ... A NULL-terminated list of attribute IDs and values,
1.717 + * beginning with the value for @a attr_id.
1.718 + */
1.719 +void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
1.720 + const char *status_id, ...) G_GNUC_NULL_TERMINATED;
1.721 +
1.722 +/**
1.723 + * Notifies libpurple that a buddy's status has been deactivated
1.724 + *
1.725 + * This is meant to be called from protocol plugins.
1.726 + *
1.727 + * @param account The account the user is on.
1.728 + * @param name The name of the buddy.
1.729 + * @param status_id The status ID.
1.730 + */
1.731 +void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
1.732 + const char *status_id);
1.733 +
1.734 +/**
1.735 + * Informs the server that our account's status changed.
1.736 + *
1.737 + * @param account The account the user is on.
1.738 + * @param old_status The previous status.
1.739 + * @param new_status The status that was activated, or deactivated
1.740 + * (in the case of independent statuses).
1.741 + */
1.742 +void purple_prpl_change_account_status(PurpleAccount *account,
1.743 + PurpleStatus *old_status,
1.744 + PurpleStatus *new_status);
1.745 +
1.746 +/**
1.747 + * Retrieves the list of stock status types from a prpl.
1.748 + *
1.749 + * @param account The account the user is on.
1.750 + * @param presence The presence for which we're going to get statuses
1.751 + *
1.752 + * @return List of statuses
1.753 + */
1.754 +GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
1.755 +
1.756 +/**
1.757 + * Send an attention request message.
1.758 + *
1.759 + * @param gc The connection to send the message on.
1.760 + * @param who Whose attention to request.
1.761 + * @param type_code An index into the prpl's attention_types list determining the type
1.762 + * of the attention request command to send. 0 if prpl only defines one
1.763 + * (for example, Yahoo and MSN), but some protocols define more (MySpaceIM).
1.764 + *
1.765 + * Note that you can't send arbitrary PurpleAttentionType's, because there is
1.766 + * only a fixed set of attention commands.
1.767 + *
1.768 + * @since 2.5.0
1.769 + */
1.770 +void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
1.771 +
1.772 +/**
1.773 + * Process an incoming attention message.
1.774 + *
1.775 + * @param gc The connection that received the attention message.
1.776 + * @param who Who requested your attention.
1.777 + * @param type_code An index into the prpl's attention_types list determining the type
1.778 + * of the attention request command to send.
1.779 + *
1.780 + * @since 2.5.0
1.781 + */
1.782 +void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
1.783 +
1.784 +/**
1.785 + * Process an incoming attention message in a chat.
1.786 + *
1.787 + * @param gc The connection that received the attention message.
1.788 + * @param id The chat id.
1.789 + * @param who Who requested your attention.
1.790 + * @param type_code An index into the prpl's attention_types list determining the type
1.791 + * of the attention request command to send.
1.792 + *
1.793 + * @since 2.5.0
1.794 + */
1.795 +void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
1.796 +
1.797 +/**
1.798 + * Determines if the contact supports the given media session type.
1.799 + *
1.800 + * @param account The account the user is on.
1.801 + * @param who The name of the contact to check capabilities for.
1.802 + *
1.803 + * @return The media caps the contact supports.
1.804 + */
1.805 +PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
1.806 + const char *who);
1.807 +
1.808 +/**
1.809 + * Initiates a media session with the given contact.
1.810 + *
1.811 + * @param account The account the user is on.
1.812 + * @param who The name of the contact to start a session with.
1.813 + * @param type The type of media session to start.
1.814 + *
1.815 + * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
1.816 + */
1.817 +gboolean purple_prpl_initiate_media(PurpleAccount *account,
1.818 + const char *who,
1.819 + PurpleMediaSessionType type);
1.820 +
1.821 +/*@}*/
1.822 +
1.823 +/**************************************************************************/
1.824 +/** @name Protocol Plugin Subsystem API */
1.825 +/**************************************************************************/
1.826 +/*@{*/
1.827 +
1.828 +/**
1.829 + * Finds a protocol plugin structure of the specified type.
1.830 + *
1.831 + * @param id The protocol plugin;
1.832 + */
1.833 +PurplePlugin *purple_find_prpl(const char *id);
1.834 +
1.835 +/*@}*/
1.836 +
1.837 +#ifdef __cplusplus
1.838 +}
1.839 +#endif
1.840 +
1.841 +#endif /* _PRPL_H_ */