Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/prpl.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     1 /**
       
     2  * @file prpl.h Protocol Plugin functions
       
     3  * @ingroup core
       
     4  */
       
     5 
       
     6 /* purple
       
     7  *
       
     8  * Purple is the legal property of its developers, whose names are too numerous
       
     9  * to list here.  Please refer to the COPYRIGHT file distributed with this
       
    10  * source distribution.
       
    11  *
       
    12  * This program is free software; you can redistribute it and/or modify
       
    13  * it under the terms of the GNU General Public License as published by
       
    14  * the Free Software Foundation; either version 2 of the License, or
       
    15  * (at your option) any later version.
       
    16  *
       
    17  * This program is distributed in the hope that it will be useful,
       
    18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
       
    19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       
    20  * GNU General Public License for more details.
       
    21  *
       
    22  * You should have received a copy of the GNU General Public License
       
    23  * along with this program; if not, write to the Free Software
       
    24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
       
    25  */
       
    26 
       
    27 /* this file should be all that prpls need to include. therefore, by including
       
    28  * this file, they should get glib, proxy, purple_connection, prpl, etc. */
       
    29 
       
    30 #ifndef _PURPLE_PRPL_H_
       
    31 #define _PURPLE_PRPL_H_
       
    32 
       
    33 typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
       
    34 /** @copydoc _PurpleAttentionType */
       
    35 typedef struct _PurpleAttentionType PurpleAttentionType;
       
    36 
       
    37 /**************************************************************************/
       
    38 /** @name Basic Protocol Information                                      */
       
    39 /**************************************************************************/
       
    40 
       
    41 typedef enum {
       
    42 	PURPLE_ICON_SCALE_DISPLAY = 0x01,		/**< We scale the icon when we display it */
       
    43 	PURPLE_ICON_SCALE_SEND = 0x02			/**< We scale the icon before we send it to the server */
       
    44 } PurpleIconScaleRules;
       
    45 
       
    46 
       
    47 /**
       
    48  * A description of a Buddy Icon specification.  This tells Purple what kind of image file
       
    49  * it should give this prpl, and what kind of image file it should expect back.
       
    50  * Dimensions less than 1 should be ignored and the image not scaled.
       
    51  */
       
    52 typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
       
    53 
       
    54 /**
       
    55  * A description of a file transfer thumbnail specification.
       
    56  * This tells the UI if and what image formats the prpl support for file
       
    57  * transfer thumbnails.
       
    58  */
       
    59 typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec;
       
    60 
       
    61 /**
       
    62  * This \#define exists just to make it easier to fill out the buddy icon
       
    63  * field in the prpl info struct for protocols that couldn't care less.
       
    64  */
       
    65 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
       
    66 
       
    67 #ifdef HAVE_UNISTD_H
       
    68 #include <unistd.h>
       
    69 #endif
       
    70 
       
    71 #include "blist.h"
       
    72 #include "conversation.h"
       
    73 #include "ft.h"
       
    74 #include "imgstore.h"
       
    75 #include "media.h"
       
    76 #include "notify.h"
       
    77 #include "proxy.h"
       
    78 #include "plugin.h"
       
    79 #include "roomlist.h"
       
    80 #include "status.h"
       
    81 #include "whiteboard.h"
       
    82 
       
    83 
       
    84 /** @copydoc PurpleBuddyIconSpec */
       
    85 struct _PurpleBuddyIconSpec {
       
    86 	/** This is a comma-delimited list of image formats or @c NULL if icons
       
    87 	 *  are not supported.  Neither the core nor the prpl will actually
       
    88 	 *  check to see if the data it's given matches this; it's entirely up
       
    89 	 *  to the UI to do what it wants
       
    90 	 */
       
    91 	char *format;
       
    92 
       
    93 	int min_width;                     /**< Minimum width of this icon  */
       
    94 	int min_height;                    /**< Minimum height of this icon */
       
    95 	int max_width;                     /**< Maximum width of this icon  */
       
    96 	int max_height;                    /**< Maximum height of this icon */
       
    97 	size_t max_filesize;               /**< Maximum size in bytes */
       
    98 	PurpleIconScaleRules scale_rules;  /**< How to stretch this icon */
       
    99 };
       
   100 
       
   101 /** Represents an entry containing information that must be supplied by the
       
   102  *  user when joining a chat.
       
   103  */
       
   104 struct proto_chat_entry {
       
   105 	const char *label;       /**< User-friendly name of the entry */
       
   106 	const char *identifier;  /**< Used by the PRPL to identify the option */
       
   107 	gboolean required;       /**< True if it's required */
       
   108 	gboolean is_int;         /**< True if the entry expects an integer */
       
   109 	int min;                 /**< Minimum value in case of integer */
       
   110 	int max;                 /**< Maximum value in case of integer */
       
   111 	gboolean secret;         /**< True if the entry is secret (password) */
       
   112 };
       
   113 
       
   114 /** Represents "nudges" and "buzzes" that you may send to a buddy to attract
       
   115  *  their attention (or vice-versa).
       
   116  */
       
   117 struct _PurpleAttentionType
       
   118 {
       
   119 	const char *name;                  /**< Shown in GUI elements */
       
   120 	const char *incoming_description;  /**< Shown when sent */
       
   121 	const char *outgoing_description;  /**< Shown when receied */
       
   122 	const char *icon_name;             /**< Icon to display (optional) */
       
   123 	const char *unlocalized_name;      /**< Unlocalized name for UIs needing it */
       
   124 
       
   125 	/* Reserved fields for future purposes */
       
   126 	gpointer _reserved2;
       
   127 	gpointer _reserved3;
       
   128 	gpointer _reserved4;
       
   129 };
       
   130 
       
   131 /**
       
   132  * Protocol options
       
   133  *
       
   134  * These should all be stuff that some plugins can do and others can't.
       
   135  */
       
   136 typedef enum
       
   137 {
       
   138 	/**
       
   139 	 * User names are unique to a chat and are not shared between rooms.
       
   140 	 *
       
   141 	 * XMPP lets you choose what name you want in chats, so it shouldn't
       
   142 	 * be pulling the aliases from the buddy list for the chat list;
       
   143 	 * it gets annoying.
       
   144 	 */
       
   145 	OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
       
   146 
       
   147 	/**
       
   148 	 * Chat rooms have topics.
       
   149 	 *
       
   150 	 * IRC and XMPP support this.
       
   151 	 */
       
   152 	OPT_PROTO_CHAT_TOPIC = 0x00000008,
       
   153 
       
   154 	/**
       
   155 	 * Don't require passwords for sign-in.
       
   156 	 *
       
   157 	 * Zephyr doesn't require passwords, so there's no
       
   158 	 * need for a password prompt.
       
   159 	 */
       
   160 	OPT_PROTO_NO_PASSWORD = 0x00000010,
       
   161 
       
   162 	/**
       
   163 	 * Notify on new mail.
       
   164 	 *
       
   165 	 * MSN and Yahoo notify you when you have new mail.
       
   166 	 */
       
   167 	OPT_PROTO_MAIL_CHECK = 0x00000020,
       
   168 
       
   169 	/**
       
   170 	 * Images in IMs.
       
   171 	 *
       
   172 	 * Oscar lets you send images in direct IMs.
       
   173 	 */
       
   174 	OPT_PROTO_IM_IMAGE = 0x00000040,
       
   175 
       
   176 	/**
       
   177 	 * Allow passwords to be optional.
       
   178 	 *
       
   179 	 * Passwords in IRC are optional, and are needed for certain
       
   180 	 * functionality.
       
   181 	 */
       
   182 	OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
       
   183 
       
   184 	/**
       
   185 	 * Allows font size to be specified in sane point size
       
   186 	 *
       
   187 	 * Probably just XMPP and Y!M
       
   188 	 */
       
   189 	OPT_PROTO_USE_POINTSIZE = 0x00000100,
       
   190 
       
   191 	/**
       
   192 	 * Set the Register button active even when the username has not
       
   193 	 * been specified.
       
   194 	 *
       
   195 	 * Gadu-Gadu doesn't need a username to register new account (because
       
   196 	 * usernames are assigned by the server).
       
   197 	 */
       
   198 	OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
       
   199 
       
   200 	/**
       
   201 	 * Indicates that slash commands are native to this protocol.
       
   202 	 * Used as a hint that unknown commands should not be sent as messages.
       
   203 	 * @since 2.1.0
       
   204 	 */
       
   205 	OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
       
   206 
       
   207 	/**
       
   208 	 * Indicates that this protocol supports sending a user-supplied message
       
   209 	 * along with an invitation.
       
   210 	 * @since 2.8.0
       
   211 	 */
       
   212 	OPT_PROTO_INVITE_MESSAGE = 0x00000800
       
   213 
       
   214 } PurpleProtocolOptions;
       
   215 
       
   216 /**
       
   217  * A protocol plugin information structure.
       
   218  *
       
   219  * Every protocol plugin initializes this structure. It is the gateway
       
   220  * between purple and the protocol plugin.  Many of these callbacks can be
       
   221  * NULL.  If a callback must be implemented, it has a comment indicating so.
       
   222  */
       
   223 struct _PurplePluginProtocolInfo
       
   224 {
       
   225 	PurpleProtocolOptions options;  /**< Protocol options.          */
       
   226 
       
   227 	GList *user_splits;      /**< A GList of PurpleAccountUserSplit */
       
   228 	GList *protocol_options; /**< A GList of PurpleAccountOption    */
       
   229 
       
   230 	PurpleBuddyIconSpec icon_spec; /**< The icon spec. */
       
   231 
       
   232 	/**
       
   233 	 * Returns the base icon name for the given buddy and account.
       
   234 	 * If buddy is NULL and the account is non-NULL, it will return the
       
   235 	 * name to use for the account's icon. If both are NULL, it will
       
   236 	 * return the name to use for the protocol's icon.
       
   237 	 *
       
   238 	 * This must be implemented.
       
   239 	 */
       
   240 	const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
       
   241 
       
   242 	/**
       
   243 	 * Fills the four char**'s with string identifiers for "emblems"
       
   244 	 * that the UI will interpret and display as relevant
       
   245 	 */
       
   246 	const char *(*list_emblem)(PurpleBuddy *buddy);
       
   247 
       
   248 	/**
       
   249 	 * Gets a short string representing this buddy's status.  This will
       
   250 	 * be shown on the buddy list.
       
   251 	 */
       
   252 	char *(*status_text)(PurpleBuddy *buddy);
       
   253 
       
   254 	/**
       
   255 	 * Allows the prpl to add text to a buddy's tooltip.
       
   256 	 */
       
   257 	void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
       
   258 
       
   259 	/**
       
   260 	 * Returns a list of #PurpleStatusType which exist for this account;
       
   261 	 * this must be implemented, and must add at least the offline and
       
   262 	 * online states.
       
   263 	 */
       
   264 	GList *(*status_types)(PurpleAccount *account);
       
   265 
       
   266 	/**
       
   267 	 * Returns a list of #PurpleMenuAction structs, which represent extra
       
   268 	 * actions to be shown in (for example) the right-click menu for @a
       
   269 	 * node.
       
   270 	 */
       
   271 	GList *(*blist_node_menu)(PurpleBlistNode *node);
       
   272 
       
   273 	/**
       
   274 	 * Returns a list of #proto_chat_entry structs, which represent
       
   275 	 * information required by the PRPL to join a chat. libpurple will
       
   276 	 * call join_chat along with the information filled by the user.
       
   277 	 *
       
   278 	 * @return A list of #proto_chat_entry structs
       
   279 	 */
       
   280 	GList *(*chat_info)(PurpleConnection *);
       
   281 
       
   282 	/**
       
   283 	 * Returns a hashtable which maps #proto_chat_entry struct identifiers
       
   284 	 * to default options as strings based on chat_name. The resulting
       
   285 	 * hashtable should be created with g_hash_table_new_full(g_str_hash,
       
   286 	 * g_str_equal, NULL, g_free);. Use #get_chat_name if you instead need
       
   287 	 * to extract a chat name from a hashtable.
       
   288 	 *
       
   289 	 * @param chat_name The chat name to be turned into components
       
   290 	 * @return Hashtable containing the information extracted from chat_name
       
   291 	 */
       
   292 	GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
       
   293 
       
   294 	/* All the server-related functions */
       
   295 
       
   296 	/** This must be implemented. */
       
   297 	void (*login)(PurpleAccount *);
       
   298 
       
   299 	/** This must be implemented. */
       
   300 	void (*close)(PurpleConnection *);
       
   301 
       
   302 	/**
       
   303 	 * This PRPL function should return a positive value on success.
       
   304 	 * If the message is too big to be sent, return -E2BIG.  If
       
   305 	 * the account is not connected, return -ENOTCONN.  If the
       
   306 	 * PRPL is unable to send the message for another reason, return
       
   307 	 * some other negative value.  You can use one of the valid
       
   308 	 * errno values, or just big something.  If the message should
       
   309 	 * not be echoed to the conversation window, return 0.
       
   310 	 */
       
   311 	int  (*send_im)(PurpleConnection *, const char *who,
       
   312 					const char *message,
       
   313 					PurpleMessageFlags flags);
       
   314 
       
   315 	void (*set_info)(PurpleConnection *, const char *info);
       
   316 
       
   317 	/**
       
   318 	 * @return If this protocol requires the PURPLE_TYPING message to
       
   319 	 *         be sent repeatedly to signify that the user is still
       
   320 	 *         typing, then the PRPL should return the number of
       
   321 	 *         seconds to wait before sending a subsequent notification.
       
   322 	 *         Otherwise the PRPL should return 0.
       
   323 	 */
       
   324 	unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
       
   325 
       
   326 	/**
       
   327 	 * Should arrange for purple_notify_userinfo() to be called with
       
   328 	 * @a who's user info.
       
   329 	 */
       
   330 	void (*get_info)(PurpleConnection *, const char *who);
       
   331 	void (*set_status)(PurpleAccount *account, PurpleStatus *status);
       
   332 
       
   333 	void (*set_idle)(PurpleConnection *, int idletime);
       
   334 	void (*change_passwd)(PurpleConnection *, const char *old_pass,
       
   335 						  const char *new_pass);
       
   336 	/**
       
   337 	 * Add a buddy to a group on the server.
       
   338 	 *
       
   339 	 * This PRPL function may be called in situations in which the buddy is
       
   340 	 * already in the specified group. If the protocol supports
       
   341 	 * authorization and the user is not already authorized to see the
       
   342 	 * status of \a buddy, \a add_buddy should request authorization.
       
   343 	 *
       
   344 	 * @deprecated Since 2.8.0, add_buddy_with_invite is preferred.
       
   345 	 * @see add_buddy_with_invite
       
   346 	 */
       
   347 	void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
       
   348 	void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
       
   349 	void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
       
   350 	void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
       
   351 	void (*add_permit)(PurpleConnection *, const char *name);
       
   352 	void (*add_deny)(PurpleConnection *, const char *name);
       
   353 	void (*rem_permit)(PurpleConnection *, const char *name);
       
   354 	void (*rem_deny)(PurpleConnection *, const char *name);
       
   355 	void (*set_permit_deny)(PurpleConnection *);
       
   356 
       
   357 	/**
       
   358 	 * Called when the user requests joining a chat. Should arrange for
       
   359 	 * #serv_got_joined_chat to be called.
       
   360 	 *
       
   361 	 * @param components A hashtable containing information required to
       
   362 	 *                   join the chat as described by the entries returned
       
   363 	 *                   by #chat_info. It may also be called when accepting
       
   364 	 *                   an invitation, in which case this matches the
       
   365 	 *                   data parameter passed to #serv_got_chat_invite.
       
   366 	 */
       
   367 	void (*join_chat)(PurpleConnection *, GHashTable *components);
       
   368 
       
   369 	/**
       
   370 	 * Called when the user refuses a chat invitation.
       
   371 	 *
       
   372 	 * @param components A hashtable containing information required to
       
   373 	 *                   join the chat as passed to #serv_got_chat_invite.
       
   374 	 */
       
   375 	void (*reject_chat)(PurpleConnection *, GHashTable *components);
       
   376 
       
   377 	/**
       
   378 	 * Returns a chat name based on the information in components. Use
       
   379 	 * #chat_info_defaults if you instead need to generate a hashtable
       
   380 	 * from a chat name.
       
   381 	 *
       
   382 	 * @param components A hashtable containing information about the chat.
       
   383 	 */
       
   384 	char *(*get_chat_name)(GHashTable *components);
       
   385 
       
   386 	/**
       
   387 	 * Invite a user to join a chat.
       
   388 	 *
       
   389 	 * @param id      The id of the chat to invite the user to.
       
   390 	 * @param message A message displayed to the user when the invitation
       
   391 	 *                is received.
       
   392 	 * @param who     The name of the user to send the invation to.
       
   393 	 */
       
   394 	void (*chat_invite)(PurpleConnection *, int id,
       
   395 						const char *message, const char *who);
       
   396 	/**
       
   397 	 * Called when the user requests leaving a chat.
       
   398 	 *
       
   399 	 * @param id The id of the chat to leave
       
   400 	 */
       
   401 	void (*chat_leave)(PurpleConnection *, int id);
       
   402 
       
   403 	/**
       
   404 	 * Send a whisper to a user in a chat.
       
   405 	 *
       
   406 	 * @param id      The id of the chat.
       
   407 	 * @param who     The name of the user to send the whisper to.
       
   408 	 * @param message The message of the whisper.
       
   409 	 */
       
   410 	void (*chat_whisper)(PurpleConnection *, int id,
       
   411 						 const char *who, const char *message);
       
   412 
       
   413 	/**
       
   414 	 * Send a message to a chat.
       
   415 	 * This PRPL function should return a positive value on success.
       
   416 	 * If the message is too big to be sent, return -E2BIG.  If
       
   417 	 * the account is not connected, return -ENOTCONN.  If the
       
   418 	 * PRPL is unable to send the message for another reason, return
       
   419 	 * some other negative value.  You can use one of the valid
       
   420 	 * errno values, or just big something.
       
   421 	 *
       
   422 	 * @param id      The id of the chat to send the message to.
       
   423 	 * @param message The message to send to the chat.
       
   424 	 * @param flags   A bitwise OR of #PurpleMessageFlags representing
       
   425 	 *                message flags.
       
   426 	 * @return 	  A positive number or 0 in case of success,
       
   427 	 *                a negative error number in case of failure.
       
   428 	 */
       
   429 	int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
       
   430 
       
   431 	/** If implemented, this will be called regularly for this prpl's
       
   432 	 *  active connections.  You'd want to do this if you need to repeatedly
       
   433 	 *  send some kind of keepalive packet to the server to avoid being
       
   434 	 *  disconnected.  ("Regularly" is defined by
       
   435 	 *  <code>KEEPALIVE_INTERVAL</code> in <tt>libpurple/connection.c</tt>.)
       
   436 	 */
       
   437 	void (*keepalive)(PurpleConnection *);
       
   438 
       
   439 	/** new user registration */
       
   440 	void (*register_user)(PurpleAccount *);
       
   441 
       
   442 	/**
       
   443 	 * @deprecated Use #PurplePluginProtocolInfo.get_info instead.
       
   444 	 */
       
   445 	void (*get_cb_info)(PurpleConnection *, int, const char *who);
       
   446 	/**
       
   447 	 * @deprecated Use #PurplePluginProtocolInfo.get_cb_real_name and
       
   448 	 *             #PurplePluginProtocolInfo.status_text instead.
       
   449 	 */
       
   450 	void (*get_cb_away)(PurpleConnection *, int, const char *who);
       
   451 
       
   452 	/** save/store buddy's alias on server list/roster */
       
   453 	void (*alias_buddy)(PurpleConnection *, const char *who,
       
   454 						const char *alias);
       
   455 
       
   456 	/** change a buddy's group on a server list/roster */
       
   457 	void (*group_buddy)(PurpleConnection *, const char *who,
       
   458 						const char *old_group, const char *new_group);
       
   459 
       
   460 	/** rename a group on a server list/roster */
       
   461 	void (*rename_group)(PurpleConnection *, const char *old_name,
       
   462 						 PurpleGroup *group, GList *moved_buddies);
       
   463 
       
   464 	void (*buddy_free)(PurpleBuddy *);
       
   465 
       
   466 	void (*convo_closed)(PurpleConnection *, const char *who);
       
   467 
       
   468 	/**
       
   469 	 *  Convert the username @a who to its canonical form.  (For example,
       
   470 	 *  AIM treats "fOo BaR" and "foobar" as the same user; this function
       
   471 	 *  should return the same normalized string for both of those.)
       
   472 	 */
       
   473 	const char *(*normalize)(const PurpleAccount *, const char *who);
       
   474 
       
   475 	/**
       
   476 	 * Set the buddy icon for the given connection to @a img.  The prpl
       
   477 	 * does NOT own a reference to @a img; if it needs one, it must
       
   478 	 * #purple_imgstore_ref(@a img) itself.
       
   479 	 */
       
   480 	void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
       
   481 
       
   482 	void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
       
   483 
       
   484 	/** Gets the real name of a participant in a chat.  For example, on
       
   485 	 *  XMPP this turns a chat room nick <tt>foo</tt> into
       
   486 	 *  <tt>room\@server/foo</tt>
       
   487 	 *  @param gc  the connection on which the room is.
       
   488 	 *  @param id  the ID of the chat room.
       
   489 	 *  @param who the nickname of the chat participant.
       
   490 	 *  @return    the real name of the participant.  This string must be
       
   491 	 *             freed by the caller.
       
   492 	 */
       
   493 	char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
       
   494 
       
   495 	void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
       
   496 
       
   497 	PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
       
   498 
       
   499 	/* room listing prpl callbacks */
       
   500 	PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
       
   501 	void (*roomlist_cancel)(PurpleRoomlist *list);
       
   502 	void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
       
   503 
       
   504 	/* file transfer callbacks */
       
   505 	gboolean (*can_receive_file)(PurpleConnection *, const char *who);
       
   506 	void (*send_file)(PurpleConnection *, const char *who, const char *filename);
       
   507 	PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
       
   508 
       
   509 	/** Checks whether offline messages to @a buddy are supported.
       
   510 	 *  @return @c TRUE if @a buddy can be sent messages while they are
       
   511 	 *          offline, or @c FALSE if not.
       
   512 	 */
       
   513 	gboolean (*offline_message)(const PurpleBuddy *buddy);
       
   514 
       
   515 	PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
       
   516 
       
   517 	/** For use in plugins that may understand the underlying protocol */
       
   518 	int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
       
   519 
       
   520 	/* room list serialize */
       
   521 	char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
       
   522 
       
   523 	/** Remove the user from the server.  The account can either be
       
   524 	 * connected or disconnected. After the removal is finished, the
       
   525 	 * connection will stay open and has to be closed!
       
   526 	 */
       
   527 	/* This is here rather than next to register_user for API compatibility
       
   528 	 * reasons.
       
   529 	 */
       
   530 	void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
       
   531 
       
   532 	/* Attention API for sending & receiving zaps/nudges/buzzes etc. */
       
   533 	gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
       
   534 	GList *(*get_attention_types)(PurpleAccount *acct);
       
   535 
       
   536 	/**
       
   537 	 * The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
       
   538 	 * This allows adding more functions to this struct without requiring a major version bump.
       
   539 	 */
       
   540 	unsigned long struct_size;
       
   541 
       
   542 	/* NOTE:
       
   543 	 * If more functions are added, they should accessed using the following syntax:
       
   544 	 *
       
   545 	 *		if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
       
   546 	 *			prpl->new_function(...);
       
   547 	 *
       
   548 	 * instead of
       
   549 	 *
       
   550 	 *		if (prpl->new_function != NULL)
       
   551 	 *			prpl->new_function(...);
       
   552 	 *
       
   553 	 * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
       
   554 	 * functions (e.g. login, send_im etc.) too.
       
   555 	 */
       
   556 
       
   557 	/** This allows protocols to specify additional strings to be used for
       
   558 	 * various purposes.  The idea is to stuff a bunch of strings in this hash
       
   559 	 * table instead of expanding the struct for every addition.  This hash
       
   560 	 * table is allocated every call and MUST be unrefed by the caller.
       
   561 	 *
       
   562 	 * @param account The account to specify.  This can be NULL.
       
   563 	 * @return The protocol's string hash table. The hash table should be
       
   564 	 *         destroyed by the caller when it's no longer needed.
       
   565 	 */
       
   566 	GHashTable *(*get_account_text_table)(PurpleAccount *account);
       
   567 
       
   568 	/**
       
   569 	 * Initiate a media session with the given contact.
       
   570 	 *
       
   571 	 * @param account The account to initiate the media session on.
       
   572 	 * @param who The remote user to initiate the session with.
       
   573 	 * @param type The type of media session to initiate.
       
   574 	 * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
       
   575 	 */
       
   576 	gboolean (*initiate_media)(PurpleAccount *account, const char *who,
       
   577 					PurpleMediaSessionType type);
       
   578 
       
   579 	/**
       
   580 	 * Checks to see if the given contact supports the given type of media session.
       
   581 	 *
       
   582 	 * @param account The account the contact is on.
       
   583 	 * @param who The remote user to check for media capability with.
       
   584 	 * @return The media caps the contact supports.
       
   585 	 */
       
   586 	PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
       
   587 					  const char *who);
       
   588 
       
   589 	/**
       
   590 	 * Returns an array of "PurpleMood"s, with the last one having
       
   591 	 * "mood" set to @c NULL.
       
   592 	 * @since 2.7.0
       
   593 	 */
       
   594 	PurpleMood *(*get_moods)(PurpleAccount *account);
       
   595 
       
   596 	/**
       
   597 	 * Set the user's "friendly name" (or alias or nickname or
       
   598 	 * whatever term you want to call it) on the server.  The
       
   599 	 * protocol plugin should call success_cb or failure_cb
       
   600 	 * *asynchronously* (if it knows immediately that the set will fail,
       
   601 	 * call one of the callbacks from an idle/0-second timeout) depending
       
   602 	 * on if the nickname is set successfully.
       
   603 	 *
       
   604 	 * @param gc    The connection for which to set an alias
       
   605 	 * @param alias The new server-side alias/nickname for this account,
       
   606 	 *              or NULL to unset the alias/nickname (or return it to
       
   607 	 *              a protocol-specific "default").
       
   608 	 * @param success_cb Callback to be called if the public alias is set
       
   609 	 * @param failure_cb Callback to be called if setting the public alias
       
   610 	 *                   fails
       
   611 	 * @see purple_account_set_public_alias
       
   612 	 * @since 2.7.0
       
   613 	 */
       
   614 	void (*set_public_alias)(PurpleConnection *gc, const char *alias,
       
   615 	                         PurpleSetPublicAliasSuccessCallback success_cb,
       
   616 	                         PurpleSetPublicAliasFailureCallback failure_cb);
       
   617 	/**
       
   618 	 * Retrieve the user's "friendly name" as set on the server.
       
   619 	 * The protocol plugin should call success_cb or failure_cb
       
   620 	 * *asynchronously* (even if it knows immediately that the get will fail,
       
   621 	 * call one of the callbacks from an idle/0-second timeout) depending
       
   622 	 * on if the nickname is retrieved.
       
   623 	 *
       
   624 	 * @param gc    The connection for which to retireve the alias
       
   625 	 * @param success_cb Callback to be called with the retrieved alias
       
   626 	 * @param failure_cb Callback to be called if the prpl is unable to
       
   627 	 *                   retrieve the alias
       
   628 	 * @see purple_account_get_public_alias
       
   629 	 * @since 2.7.0
       
   630 	 */
       
   631 	void (*get_public_alias)(PurpleConnection *gc,
       
   632 	                         PurpleGetPublicAliasSuccessCallback success_cb,
       
   633 	                         PurpleGetPublicAliasFailureCallback failure_cb);
       
   634 
       
   635 	/**
       
   636 	 * Add a buddy to a group on the server.
       
   637 	 *
       
   638 	 * This PRPL function may be called in situations in which the buddy is
       
   639 	 * already in the specified group. If the protocol supports
       
   640 	 * authorization and the user is not already authorized to see the
       
   641 	 * status of \a buddy, \a add_buddy should request authorization.
       
   642 	 *
       
   643 	 * If authorization is required, then use the supplied invite message.
       
   644 	 *
       
   645 	 * @since 2.8.0
       
   646 	 */
       
   647 	void (*add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
       
   648 	void (*add_buddies_with_invite)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
       
   649 };
       
   650 
       
   651 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
       
   652 	(((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
       
   653 	  || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
       
   654 	 prpl->member != NULL)
       
   655 
       
   656 
       
   657 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
       
   658 	((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
       
   659 
       
   660 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
       
   661 	((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
       
   662 
       
   663 #ifdef __cplusplus
       
   664 extern "C" {
       
   665 #endif
       
   666 
       
   667 /**************************************************************************/
       
   668 /** @name Attention Type API                                              */
       
   669 /**************************************************************************/
       
   670 /*@{*/
       
   671 
       
   672 /**
       
   673  * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
       
   674  *
       
   675  * @param ulname A non-localized string that can be used by UIs in need of such
       
   676  *               non-localized strings.  This should be the same as @a name,
       
   677  *               without localization.
       
   678  * @param name A localized string that the UI may display for the event. This
       
   679  *             should be the same string as @a ulname, with localization.
       
   680  * @param inc_desc A localized description shown when the event is received.
       
   681  * @param out_desc A localized description shown when the event is sent.
       
   682  * @return A pointer to the new object.
       
   683  * @since 2.4.0
       
   684  */
       
   685 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
       
   686 								const char *inc_desc, const char *out_desc);
       
   687 
       
   688 /**
       
   689  * Sets the displayed name of the attention-demanding event.
       
   690  *
       
   691  * @param type The attention type.
       
   692  * @param name The localized name that will be displayed by UIs. This should be
       
   693  *             the same string given as the unlocalized name, but with
       
   694  *             localization.
       
   695  * @since 2.4.0
       
   696  */
       
   697 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
       
   698 
       
   699 /**
       
   700  * Sets the description of the attention-demanding event shown in  conversations
       
   701  * when the event is received.
       
   702  *
       
   703  * @param type The attention type.
       
   704  * @param desc The localized description for incoming events.
       
   705  * @since 2.4.0
       
   706  */
       
   707 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
       
   708 
       
   709 /**
       
   710  * Sets the description of the attention-demanding event shown in conversations
       
   711  * when the event is sent.
       
   712  *
       
   713  * @param type The attention type.
       
   714  * @param desc The localized description for outgoing events.
       
   715  * @since 2.4.0
       
   716  */
       
   717 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
       
   718 
       
   719 /**
       
   720  * Sets the name of the icon to display for the attention event; this is optional.
       
   721  *
       
   722  * @param type The attention type.
       
   723  * @param name The icon's name.
       
   724  * @note Icons are optional for attention events.
       
   725  * @since 2.4.0
       
   726  */
       
   727 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
       
   728 
       
   729 /**
       
   730  * Sets the unlocalized name of the attention event; some UIs may need this,
       
   731  * thus it is required.
       
   732  *
       
   733  * @param type The attention type.
       
   734  * @param ulname The unlocalized name.  This should be the same string given as
       
   735  *               the localized name, but without localization.
       
   736  * @since 2.4.0
       
   737  */
       
   738 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
       
   739 
       
   740 /**
       
   741  * Get the attention type's name as displayed by the UI.
       
   742  *
       
   743  * @param type The attention type.
       
   744  * @return The name.
       
   745  * @since 2.4.0
       
   746  */
       
   747 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
       
   748 
       
   749 /**
       
   750  * Get the attention type's description shown when the event is received.
       
   751  *
       
   752  * @param type The attention type.
       
   753  * @return The description.
       
   754  * @since 2.4.0
       
   755  */
       
   756 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
       
   757 
       
   758 /**
       
   759  * Get the attention type's description shown when the event is sent.
       
   760  *
       
   761  * @param type The attention type.
       
   762  * @return The description.
       
   763  * @since 2.4.0
       
   764  */
       
   765 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
       
   766 
       
   767 /**
       
   768  * Get the attention type's icon name.
       
   769  *
       
   770  * @param type The attention type.
       
   771  * @return The icon name or @c NULL if unset/empty.
       
   772  * @note Icons are optional for attention events.
       
   773  * @since 2.4.0
       
   774  */
       
   775 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
       
   776 
       
   777 /**
       
   778  * Get the attention type's unlocalized name; this is useful for some UIs.
       
   779  *
       
   780  * @param type The attention type
       
   781  * @return The unlocalized name.
       
   782  * @since 2.4.0
       
   783  */
       
   784 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
       
   785 
       
   786 /*@}*/
       
   787 
       
   788 /**************************************************************************/
       
   789 /** @name Protocol Plugin API                                             */
       
   790 /**************************************************************************/
       
   791 /*@{*/
       
   792 
       
   793 /**
       
   794  * Notifies Purple that our account's idle state and time have changed.
       
   795  *
       
   796  * This is meant to be called from protocol plugins.
       
   797  *
       
   798  * @param account   The account.
       
   799  * @param idle      The user's idle state.
       
   800  * @param idle_time The user's idle time.
       
   801  */
       
   802 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
       
   803 								time_t idle_time);
       
   804 
       
   805 /**
       
   806  * Notifies Purple of our account's log-in time.
       
   807  *
       
   808  * This is meant to be called from protocol plugins.
       
   809  *
       
   810  * @param account    The account the user is on.
       
   811  * @param login_time The user's log-in time.
       
   812  */
       
   813 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
       
   814 
       
   815 /**
       
   816  * Notifies Purple that our account's status has changed.
       
   817  *
       
   818  * This is meant to be called from protocol plugins.
       
   819  *
       
   820  * @param account   The account the user is on.
       
   821  * @param status_id The status ID.
       
   822  * @param ...       A NULL-terminated list of attribute IDs and values,
       
   823  *                  beginning with the value for @a attr_id.
       
   824  */
       
   825 void purple_prpl_got_account_status(PurpleAccount *account,
       
   826 								  const char *status_id, ...) G_GNUC_NULL_TERMINATED;
       
   827 
       
   828 /**
       
   829  * Notifies Purple that our account's actions have changed. This is only
       
   830  * called after the initial connection. Emits the account-actions-changed
       
   831  * signal.
       
   832  *
       
   833  * This is meant to be called from protocol plugins.
       
   834  *
       
   835  * @param account   The account.
       
   836  *
       
   837  * @see account-actions-changed
       
   838  * @since 2.6.0
       
   839  */
       
   840 void purple_prpl_got_account_actions(PurpleAccount *account);
       
   841 
       
   842 /**
       
   843  * Notifies Purple that a buddy's idle state and time have changed.
       
   844  *
       
   845  * This is meant to be called from protocol plugins.
       
   846  *
       
   847  * @param account   The account the user is on.
       
   848  * @param name      The name of the buddy.
       
   849  * @param idle      The user's idle state.
       
   850  * @param idle_time The user's idle time.  This is the time at
       
   851  *                  which the user became idle, in seconds since
       
   852  *                  the epoch.  If the PRPL does not know this value
       
   853  *                  then it should pass 0.
       
   854  */
       
   855 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
       
   856 							 gboolean idle, time_t idle_time);
       
   857 
       
   858 /**
       
   859  * Notifies Purple of a buddy's log-in time.
       
   860  *
       
   861  * This is meant to be called from protocol plugins.
       
   862  *
       
   863  * @param account    The account the user is on.
       
   864  * @param name       The name of the buddy.
       
   865  * @param login_time The user's log-in time.
       
   866  */
       
   867 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
       
   868 								   time_t login_time);
       
   869 
       
   870 /**
       
   871  * Notifies Purple that a buddy's status has been activated.
       
   872  *
       
   873  * This is meant to be called from protocol plugins.
       
   874  *
       
   875  * @param account   The account the user is on.
       
   876  * @param name      The name of the buddy.
       
   877  * @param status_id The status ID.
       
   878  * @param ...       A NULL-terminated list of attribute IDs and values,
       
   879  *                  beginning with the value for @a attr_id.
       
   880  */
       
   881 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
       
   882 							   const char *status_id, ...) G_GNUC_NULL_TERMINATED;
       
   883 
       
   884 /**
       
   885  * Notifies libpurple that a buddy's status has been deactivated
       
   886  *
       
   887  * This is meant to be called from protocol plugins.
       
   888  *
       
   889  * @param account   The account the user is on.
       
   890  * @param name      The name of the buddy.
       
   891  * @param status_id The status ID.
       
   892  */
       
   893 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
       
   894 					const char *status_id);
       
   895 
       
   896 /**
       
   897  * Informs the server that our account's status changed.
       
   898  *
       
   899  * @param account    The account the user is on.
       
   900  * @param old_status The previous status.
       
   901  * @param new_status The status that was activated, or deactivated
       
   902  *                   (in the case of independent statuses).
       
   903  */
       
   904 void purple_prpl_change_account_status(PurpleAccount *account,
       
   905 									 PurpleStatus *old_status,
       
   906 									 PurpleStatus *new_status);
       
   907 
       
   908 /**
       
   909  * Retrieves the list of stock status types from a prpl.
       
   910  *
       
   911  * @param account The account the user is on.
       
   912  * @param presence The presence for which we're going to get statuses
       
   913  *
       
   914  * @return List of statuses
       
   915  */
       
   916 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
       
   917 
       
   918 /**
       
   919  * Send an attention request message.
       
   920  *
       
   921  * @param gc The connection to send the message on.
       
   922  * @param who Whose attention to request.
       
   923  * @param type_code An index into the prpl's attention_types list determining the type
       
   924  *        of the attention request command to send. 0 if prpl only defines one
       
   925  *        (for example, Yahoo and MSN), but some protocols define more (MySpaceIM).
       
   926  *
       
   927  * Note that you can't send arbitrary PurpleAttentionType's, because there is
       
   928  * only a fixed set of attention commands.
       
   929  *
       
   930  * @since 2.5.0
       
   931  */
       
   932 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
       
   933 
       
   934 /**
       
   935  * Process an incoming attention message.
       
   936  *
       
   937  * @param gc The connection that received the attention message.
       
   938  * @param who Who requested your attention.
       
   939  * @param type_code An index into the prpl's attention_types list determining the type
       
   940  *        of the attention request command to send.
       
   941  *
       
   942  * @since 2.5.0
       
   943  */
       
   944 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
       
   945 
       
   946 /**
       
   947  * Process an incoming attention message in a chat.
       
   948  *
       
   949  * @param gc The connection that received the attention message.
       
   950  * @param id The chat id.
       
   951  * @param who Who requested your attention.
       
   952  * @param type_code An index into the prpl's attention_types list determining the type
       
   953  *        of the attention request command to send.
       
   954  *
       
   955  * @since 2.5.0
       
   956  */
       
   957 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
       
   958 
       
   959 /**
       
   960  * Determines if the contact supports the given media session type.
       
   961  *
       
   962  * @param account The account the user is on.
       
   963  * @param who The name of the contact to check capabilities for.
       
   964  *
       
   965  * @return The media caps the contact supports.
       
   966  */
       
   967 PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
       
   968 				  const char *who);
       
   969 
       
   970 /**
       
   971  * Initiates a media session with the given contact.
       
   972  *
       
   973  * @param account The account the user is on.
       
   974  * @param who The name of the contact to start a session with.
       
   975  * @param type The type of media session to start.
       
   976  *
       
   977  * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media session or stream will be successfully created)
       
   978  */
       
   979 gboolean purple_prpl_initiate_media(PurpleAccount *account,
       
   980 					const char *who,
       
   981 					PurpleMediaSessionType type);
       
   982 
       
   983 /**
       
   984  * Signals that the prpl received capabilities for the given contact.
       
   985  *
       
   986  * This function is intended to be used only by prpls.
       
   987  *
       
   988  * @param account The account the user is on.
       
   989  * @param who The name of the contact for which capabilities have been received.
       
   990  * @since 2.7.0
       
   991  */
       
   992 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
       
   993 
       
   994 /*@}*/
       
   995 
       
   996 /**************************************************************************/
       
   997 /** @name Protocol Plugin Subsystem API                                   */
       
   998 /**************************************************************************/
       
   999 /*@{*/
       
  1000 
       
  1001 /**
       
  1002  * Finds a protocol plugin structure of the specified type.
       
  1003  *
       
  1004  * @param id The protocol plugin;
       
  1005  */
       
  1006 PurplePlugin *purple_find_prpl(const char *id);
       
  1007 
       
  1008 /*@}*/
       
  1009 
       
  1010 #ifdef __cplusplus
       
  1011 }
       
  1012 #endif
       
  1013 
       
  1014 #ifdef __COVERITY__
       
  1015 #undef PURPLE_PROTOCOL_PLUGIN_HAS_FUNC
       
  1016 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) (prpl->member != NULL)
       
  1017 #endif
       
  1018 
       
  1019 #endif /* _PRPL_H_ */