diff libpurple/prpl.h @ 19484:472bcd9d502e

propagate from branch 'im.pidgin.pidgin' (head 384c9116031084a2f41659dc9e9a4aa7bba55d86) to branch 'im.pidgin.soc.2007.xmpp' (head 3826e19f149ec8f3f701f463eec7825eed512d05)

--- a/libpurple/prpl.h	Fri Aug 17 02:26:42 2007 +0000
+++ b/libpurple/prpl.h	Mon Aug 27 21:59:11 2007 +0000
@@ -30,6 +30,7 @@
 #define _PURPLE_PRPL_H_
 
 typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
+typedef struct _PurpleAttentionType PurpleAttentionType;
 
 /**************************************************************************/
 /** @name Basic Protocol Information                                      */
@@ -91,6 +92,20 @@
 	gboolean secret;
 };
 
+struct _PurpleAttentionType
+{
+	const char *name;                  /**< Shown in GUI elements */
+	const char *incoming_description;  /**< Shown when sent */
+	const char *outgoing_description;  /**< Shown when receied */
+	const char *icon_name;             /**< Icon to display (optional) */
+
+	/* Reserved fields for future purposes */
+	gpointer _reserved1;
+	gpointer _reserved2;
+	gpointer _reserved3;
+	gpointer _reserved4;
+};
+
 /**
  * Protocol options
  *
@@ -177,10 +192,10 @@
 {
 	PurpleProtocolOptions options;  /**< Protocol options.          */
 
-	GList *user_splits;      /* A GList of PurpleAccountUserSplit */
-	GList *protocol_options; /* A GList of PurpleAccountOption    */
+	GList *user_splits;      /**< A GList of PurpleAccountUserSplit */
+	GList *protocol_options; /**< A GList of PurpleAccountOption    */
 
-	PurpleBuddyIconSpec icon_spec; /* The icon spec. */
+	PurpleBuddyIconSpec icon_spec; /**< The icon spec. */
 
 	/**
 	 * Returns the base icon name for the given buddy and account.
@@ -268,22 +283,22 @@
 	int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
 	void (*keepalive)(PurpleConnection *);
 
-	/* new user registration */
+	/** new user registration */
 	void (*register_user)(PurpleAccount *);
 
 	/* get "chat buddy" info and away message */
 	void (*get_cb_info)(PurpleConnection *, int, const char *who);
 	void (*get_cb_away)(PurpleConnection *, int, const char *who);
 
-	/* save/store buddy's alias on server list/roster */
+	/** save/store buddy's alias on server list/roster */
 	void (*alias_buddy)(PurpleConnection *, const char *who,
 						const char *alias);
 
-	/* change a buddy's group on a server list/roster */
+	/** change a buddy's group on a server list/roster */
 	void (*group_buddy)(PurpleConnection *, const char *who,
 						const char *old_group, const char *new_group);
 
-	/* rename a group on a server list/roster */
+	/** rename a group on a server list/roster */
 	void (*rename_group)(PurpleConnection *, const char *old_name,
 						 PurpleGroup *group, GList *moved_buddies);
 
@@ -291,10 +306,18 @@
 
 	void (*convo_closed)(PurpleConnection *, const char *who);
 
-	const char *(*normalize)(const PurpleAccount *, const char *);
+	/**
+	 *  Convert the username @a who to its canonical form.  (For example,
+	 *  AIM treats "fOo BaR" and "foobar" as the same user; this function
+	 *  should return the same normalized string for both of those.)
+	 */
+	const char *(*normalize)(const PurpleAccount *, const char *who);
 
-	/* The prpl does NOT own a reference to img.  If it needs one, it
-	 * must purple_imgstore_ref(img) itself. */
+	/**
+	 * Set the buddy icon for the given connection to @a img.  The prpl
+	 * does NOT own a reference to @a img; if it needs one, it must
+	 * #purple_imgstore_ref(@a img) itself.
+	 */
 	void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
 
 	void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
@@ -318,7 +341,7 @@
 
 	PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
 
-	/* For use in plugins that may understand the underlying protocol */
+	/** For use in plugins that may understand the underlying protocol */
 	int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
 
 	/* room list serialize */
@@ -330,8 +353,10 @@
 	 */
 	void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
 	
-	void (*_purple_reserved1)(void);
-	void (*_purple_reserved2)(void);
+	/* Attention API for sending & receiving zaps/nudges/buzzes etc. */
+	gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
+	GList *(*attention_types)(PurpleAccount *acct);
+
 	void (*_purple_reserved3)(void);
 };