1.1 --- a/Frameworks/libpurple.framework/Versions/0.6.0/Headers/prpl.h Fri Aug 21 13:24:36 2009 -0700
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,838 +0,0 @@
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_ */