pidgin: libpurple/prpl.h comparison

comparison libpurple/prpl.h @ 32672:3828a61c44da

A boring and large patch so I can merge heads.

author	Elliott Sales de Andrade <qulogic@pidgin.im>
date	Fri, 23 Dec 2011 08:21:58 +0000
parents	96e66fbe2881
children

comparison

equal deleted inserted replaced

-:0e69949b3e61
+:3828a61c44da
 #ifndef _PURPLE_PRPL_H_
 #define _PURPLE_PRPL_H_
 typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
-/** @copydoc _PurpleAttentionType */
+/** Represents "nudges" and "buzzes" that you may send to a buddy to attract
+*  their attention (or vice-versa).
+*/
 typedef struct _PurpleAttentionType PurpleAttentionType;
 /**************************************************************************/
 /** @name Basic Protocol Information                                      */
 /**************************************************************************/
 	int min;                 /**< Minimum value in case of integer */
 	int max;                 /**< Maximum value in case of integer */
 	gboolean secret;         /**< True if the entry is secret (password) */
 };
-/** Represents "nudges" and "buzzes" that you may send to a buddy to attract
-*  their attention (or vice-versa).
-*/
-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) */
-	const char *unlocalized_name;      /**< Unlocalized name for UIs needing it */
-	/* Reserved fields for future purposes */
-	gpointer _reserved2;
-	gpointer _reserved3;
-	gpointer _reserved4;
-};
 /**
 * Protocol options
 *
 * These should all be stuff that some plugins can do and others can't.
 */
 	OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
 	/**
 	 * Indicates that slash commands are native to this protocol.
 	 * Used as a hint that unknown commands should not be sent as messages.
-	 * @since 2.1.0
 	 */
 	OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
 	/**
 	 * Indicates that this protocol supports sending a user-supplied message
 	 * along with an invitation.
-	 * @since 2.8.0
 	 */
 	OPT_PROTO_INVITE_MESSAGE = 0x00000800
 } PurpleProtocolOptions;
 * between purple and the protocol plugin.  Many of these callbacks can be
 * NULL.  If a callback must be implemented, it has a comment indicating so.
 */
 struct _PurplePluginProtocolInfo
 {
+	/**
+	 * The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
+	 * This allows adding more functions to this struct without requiring a major version bump.
+	 */
+	unsigned long struct_size;
+	/* NOTE:
+	 * If more functions are added, they should accessed using the following syntax:
+	 *
+	 *		if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
+	 *			prpl->new_function(...);
+	 *
+	 * instead of
+	 *
+	 *		if (prpl->new_function != NULL)
+	 *			prpl->new_function(...);
+	 *
+	 * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
+	 * functions (e.g. login, send_im etc.) too.
+	 */
 	PurpleProtocolOptions options;  /**< Protocol options.          */
 	GList *user_splits;      /**< A GList of PurpleAccountUserSplit */
 	GList *protocol_options; /**< A GList of PurpleAccountOption    */
 	void (*set_status)(PurpleAccount *account, PurpleStatus *status);
 	void (*set_idle)(PurpleConnection *, int idletime);
 	void (*change_passwd)(PurpleConnection *, const char *old_pass,
 						  const char *new_pass);
 	/**
 	 * Add a buddy to a group on the server.
 	 *
 	 * This PRPL function may be called in situations in which the buddy is
 	 * already in the specified group. If the protocol supports
 	 * authorization and the user is not already authorized to see the
 	 * status of \a buddy, \a add_buddy should request authorization.
 	 *
-	 * @deprecated Since 2.8.0, add_buddy_with_invite is preferred.
+	 * If authorization is required, then use the supplied invite message.
-	 * @see add_buddy_with_invite
+	 */
-	 */
+	void (*add_buddy)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
-	void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
+	void (*add_buddies)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
-	void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
 	void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
 	void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
 	void (*add_permit)(PurpleConnection *, const char *name);
 	void (*add_deny)(PurpleConnection *, const char *name);
 	void (*rem_permit)(PurpleConnection *, const char *name);
 	/**
 	 * @deprecated Use #PurplePluginProtocolInfo.get_info instead.
 	 */
 	void (*get_cb_info)(PurpleConnection *, int, const char *who);
-	/**
-	 * @deprecated Use #PurplePluginProtocolInfo.get_cb_real_name and
-	 *             #PurplePluginProtocolInfo.status_text instead.
-	 */
-	void (*get_cb_away)(PurpleConnection *, int, const char *who);
 	/** save/store buddy's alias on server list/roster */
 	void (*alias_buddy)(PurpleConnection *, const char *who,
 						const char *alias);
 	/* Attention API for sending & receiving zaps/nudges/buzzes etc. */
 	gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
 	GList *(*get_attention_types)(PurpleAccount *acct);
-	/**
-	 * The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
-	 * This allows adding more functions to this struct without requiring a major version bump.
-	 */
-	unsigned long struct_size;
-	/* NOTE:
-	 * If more functions are added, they should accessed using the following syntax:
-	 *
-	 *		if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
-	 *			prpl->new_function(...);
-	 *
-	 * instead of
-	 *
-	 *		if (prpl->new_function != NULL)
-	 *			prpl->new_function(...);
-	 *
-	 * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
-	 * functions (e.g. login, send_im etc.) too.
-	 */
 	/** This allows protocols to specify additional strings to be used for
 	 * various purposes.  The idea is to stuff a bunch of strings in this hash
 	 * table instead of expanding the struct for every addition.  This hash
 	 * table is allocated every call and MUST be unrefed by the caller.
 	 *
 					  const char *who);
 	/**
 	 * Returns an array of "PurpleMood"s, with the last one having
 	 * "mood" set to @c NULL.
-	 * @since 2.7.0
 	 */
 	PurpleMood *(*get_moods)(PurpleAccount *account);
 	/**
 	 * Set the user's "friendly name" (or alias or nickname or
 	 *              a protocol-specific "default").
 	 * @param success_cb Callback to be called if the public alias is set
 	 * @param failure_cb Callback to be called if setting the public alias
 	 *                   fails
 	 * @see purple_account_set_public_alias
-	 * @since 2.7.0
 	 */
 	void (*set_public_alias)(PurpleConnection *gc, const char *alias,
 	                         PurpleSetPublicAliasSuccessCallback success_cb,
 	                         PurpleSetPublicAliasFailureCallback failure_cb);
 	/**
 	 * @param gc    The connection for which to retireve the alias
 	 * @param success_cb Callback to be called with the retrieved alias
 	 * @param failure_cb Callback to be called if the prpl is unable to
 	 *                   retrieve the alias
 	 * @see purple_account_get_public_alias
-	 * @since 2.7.0
 	 */
 	void (*get_public_alias)(PurpleConnection *gc,
 	                         PurpleGetPublicAliasSuccessCallback success_cb,
 	                         PurpleGetPublicAliasFailureCallback failure_cb);
-	/**
-	 * Add a buddy to a group on the server.
-	 *
-	 * This PRPL function may be called in situations in which the buddy is
-	 * already in the specified group. If the protocol supports
-	 * authorization and the user is not already authorized to see the
-	 * status of \a buddy, \a add_buddy should request authorization.
-	 *
-	 * If authorization is required, then use the supplied invite message.
-	 *
-	 * @since 2.8.0
-	 */
-	void (*add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
-	void (*add_buddies_with_invite)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
 };
 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
-	(((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
+	(G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size && \
-	  || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
 	 prpl->member != NULL)
 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
 	((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
 *               without localization.
 * @param name A localized string that the UI may display for the event. This
 *             should be the same string as @a ulname, with localization.
 * @param inc_desc A localized description shown when the event is received.
 * @param out_desc A localized description shown when the event is sent.
+*
 * @return A pointer to the new object.
-* @since 2.4.0
 */
 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
 								const char *inc_desc, const char *out_desc);
 /**
 *
 * @param type The attention type.
 * @param name The localized name that will be displayed by UIs. This should be
 *             the same string given as the unlocalized name, but with
 *             localization.
-* @since 2.4.0
 */
 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
 /**
 * Sets the description of the attention-demanding event shown in  conversations
 * when the event is received.
 *
 * @param type The attention type.
 * @param desc The localized description for incoming events.
-* @since 2.4.0
 */
 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
 /**
 * Sets the description of the attention-demanding event shown in conversations
 * when the event is sent.
 *
 * @param type The attention type.
 * @param desc The localized description for outgoing events.
-* @since 2.4.0
 */
 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
 /**
 * Sets the name of the icon to display for the attention event; this is optional.
 *
 * @param type The attention type.
 * @param name The icon's name.
 * @note Icons are optional for attention events.
-* @since 2.4.0
 */
 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
 /**
 * Sets the unlocalized name of the attention event; some UIs may need this,
 * thus it is required.
 *
 * @param type The attention type.
 * @param ulname The unlocalized name.  This should be the same string given as
 *               the localized name, but without localization.
-* @since 2.4.0
 */
 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
 /**
 * Get the attention type's name as displayed by the UI.
 *
 * @param type The attention type.
+*
 * @return The name.
-* @since 2.4.0
 */
 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
 /**
 * Get the attention type's description shown when the event is received.
 *
 * @param type The attention type.
 * @return The description.
-* @since 2.4.0
 */
 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
 /**
 * Get the attention type's description shown when the event is sent.
 *
 * @param type The attention type.
 * @return The description.
-* @since 2.4.0
 */
 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
 /**
 * Get the attention type's icon name.
 *
 * @param type The attention type.
 * @return The icon name or @c NULL if unset/empty.
 * @note Icons are optional for attention events.
-* @since 2.4.0
 */
 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
 /**
 * Get the attention type's unlocalized name; this is useful for some UIs.
 *
 * @param type The attention type
 * @return The unlocalized name.
-* @since 2.4.0
 */
 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
 /*@}*/
 * This is meant to be called from protocol plugins.
 *
 * @param account   The account.
 *
 * @see account-actions-changed
-* @since 2.6.0
 */
 void purple_prpl_got_account_actions(PurpleAccount *account);
 /**
 * Notifies Purple that a buddy's idle state and time have changed.
 *        of the attention request command to send. 0 if prpl only defines one
 *        (for example, Yahoo and MSN), but some protocols define more (MySpaceIM).
 *
 * Note that you can't send arbitrary PurpleAttentionType's, because there is
 * only a fixed set of attention commands.
-*
-* @since 2.5.0
 */
 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
 /**
 * Process an incoming attention message.
 *
 * @param gc The connection that received the attention message.
 * @param who Who requested your attention.
 * @param type_code An index into the prpl's attention_types list determining the type
 *        of the attention request command to send.
-*
-* @since 2.5.0
 */
 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
 /**
 * Process an incoming attention message in a chat.
 * @param gc The connection that received the attention message.
 * @param id The chat id.
 * @param who Who requested your attention.
 * @param type_code An index into the prpl's attention_types list determining the type
 *        of the attention request command to send.
-*
-* @since 2.5.0
 */
 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
 /**
 * Determines if the contact supports the given media session type.
 *
 * This function is intended to be used only by prpls.
 *
 * @param account The account the user is on.
 * @param who The name of the contact for which capabilities have been received.
-* @since 2.7.0
 */
 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
 /*@}*/

Mercurial > pidgin

comparison libpurple/prpl.h @ 32672:3828a61c44da