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