comparison libpurple/blist.h @ 32687:02a2e8183b1d

Clean the API documentation in preparation for 3.0.0 by removing all the old @since tags.

32685:9d5b87e1a4d0

{
	PURPLE_BLIST_NODE_FLAG_NO_SAVE      = 1 << 0 /**< node should not be saved with the buddy list */

} PurpleBlistNodeFlags;

/**
 * @since 2.6.0
 */
#define PURPLE_BLIST_NODE(obj) ((PurpleBlistNode *)(obj))

#define PURPLE_BLIST_NODE_HAS_FLAG(b, f) (purple_blist_node_get_flags((PurpleBlistNode*)(b)) & (f))
#define PURPLE_BLIST_NODE_SHOULD_SAVE(b) (! PURPLE_BLIST_NODE_HAS_FLAG(b, PURPLE_BLIST_NODE_FLAG_NO_SAVE))

#define PURPLE_BLIST_NODE_NAME(n) (purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE  ? purple_chat_get_name((PurpleChat*)n) :        \
				     purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE ? purple_buddy_get_name((PurpleBuddy*)n) : NULL)

/**
 * @since 2.6.0
 */
#define PURPLE_GROUP(obj) ((PurpleGroup *)(obj))

/**
 * @since 2.6.0
 */
#define PURPLE_CONTACT(obj) ((PurpleContact *)(obj))

/**
 * @since 2.6.0
 */
#define PURPLE_BUDDY(obj) ((PurpleBuddy *)(obj))

/**
 * @since 2.6.0
 */
#define PURPLE_CHAT(obj) ((PurpleChat *)(obj))

#include "account.h"
#include "buddyicon.h"
#include "media.h"

	 * Implementation of this UI op is OPTIONAL. If not implemented, it will
	 * be set to a fallback function that saves data to blist.xml like in
	 * previous libpurple versions.
	 *
	 * @param node    The node which has been modified.
	 *
	 * @since 2.6.0.
	 */
	void (*save_node)(PurpleBlistNode *node);

	/**
	 * Called when a node is about to be removed from the buddy list.

	 * Implementation of this UI op is OPTIONAL. If not implemented, it will
	 * be set to a fallback function that saves data to blist.xml like in
	 * previous libpurple versions.
	 *
	 * @param node  The node which has been modified.
	 * @since 2.6.0.
	 */
	void (*remove_node)(PurpleBlistNode *node);

	/**
	 * Called to save all the data for an account. If the UI sets this,

	 * be set to a fallback function that saves data to blist.xml like in
	 * previous libpurple versions.
	 *
	 * @param account  The account whose data to save. If NULL, save all data
	 *                  for all accounts.
	 * @since 2.6.0.
	 */
	void (*save_account)(PurpleAccount *account);

	void (*_purple_reserved1)(void);
};

 *
 * @return A list of every buddy in the list. Caller is responsible for
 *         freeing the list.
 *
 * @see purple_find_buddies
 * @since 2.6.0
 */
GSList *purple_blist_get_buddies(void);

/**
 * Returns the UI data for the list.
 *
 * @return The UI data for the list.
 *
 * @since 2.6.0
 */
gpointer purple_blist_get_ui_data(void);

/**
 * Sets the UI data for the list.
 *
 * @param ui_data The UI data for the list.
 *
 * @since 2.6.0
 */
void purple_blist_set_ui_data(gpointer ui_data);

/**
 * Returns the next node of a given node. This function is to be used to iterate

/**
 * Returns the parent node of a given node.
 *
 * @param node A node.
 * @return  The parent node.
 * @since 2.4.0
 * @see purple_blist_node_get_first_child
 * @see purple_blist_node_get_sibling_next
 * @see purple_blist_node_get_sibling_prev
 * @see purple_blist_node_next
 */

/**
 * Returns the the first child node of a given node.
 *
 * @param node A node.
 * @return  The child node.
 * @since 2.4.0
 * @see purple_blist_node_get_parent
 * @see purple_blist_node_get_sibling_next
 * @see purple_blist_node_get_sibling_prev
 * @see purple_blist_node_next
 */

/**
 * Returns the sibling node of a given node.
 *
 * @param node A node.
 * @return  The sibling node.
 * @since 2.4.0
 * @see purple_blist_node_get_parent
 * @see purple_blist_node_get_first_child
 * @see purple_blist_node_get_sibling_prev
 * @see purple_blist_node_next
 */

/**
 * Returns the previous sibling node of a given node.
 *
 * @param node A node.
 * @return  The sibling node.
 * @since 2.4.0
 * @see purple_blist_node_get_parent
 * @see purple_blist_node_get_first_child
 * @see purple_blist_node_get_sibling_next
 * @see purple_blist_node_next
 */

/**
 * Returns the UI data of a given node.
 *
 * @param node The node.
 * @return The UI data.
 * @since 2.6.0
 */
gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node);

/**
 * Sets the UI data of a given node.
 *
 * @param node The node.
 * @param ui_data The UI data.
 *
 * @since 2.6.0
 */
void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data);

/**
 * Shows the buddy list, creating a new one if necessary.

 *
 * @param buddy The buddy.
 * @return      The protocol data.
 *
 * @see purple_buddy_set_protocol_data()
 * @since 2.6.0
 */
gpointer purple_buddy_get_protocol_data(const PurpleBuddy *buddy);

/**
 * Sets a buddy's protocol-specific data.

 *
 * @param buddy The buddy.
 * @param data  The data.
 *
 * @see purple_buddy_get_protocol_data()
 * @since 2.6.0
 */
void purple_buddy_set_protocol_data(PurpleBuddy *buddy, gpointer data);

/**
 * Returns a buddy's contact.

/**
 * Gets the media caps from a buddy.
 *
 * @param buddy The buddy.
 * @return      The media caps.
 *
 * @since 2.7.0
 */
PurpleMediaCaps purple_buddy_get_media_caps(const PurpleBuddy *buddy);

/**
 * Sets the media caps for a buddy.

/**
 * Gets the PurpleGroup from a PurpleContact
 *
 * @param contact  The contact
 * @return         The group
 *
 * @since 2.7.0
 */
PurpleGroup *purple_contact_get_group(const PurpleContact *contact);

/**
 * Adds a new contact to the buddy list.

/**
 * Returns the local alias for the buddy, or @c NULL if none exists.
 *
 * @param buddy  The buddy
 * @return       The local alias for the buddy
 *
 * @since 2.6.0
 */
const char *purple_buddy_get_local_buddy_alias(PurpleBuddy *buddy);

/**
 * Returns the correct name to display for a blist chat.

 * Returns the account the chat belongs to.
 *
 * @param chat  The chat.
 *
 * @return  The account the chat belongs to.
 *
 * @since 2.4.0
 */
PurpleAccount *purple_chat_get_account(PurpleChat *chat);

/**
 * Get a hashtable containing information about a chat.
 *
 * @param chat  The chat.
 *
 * @constreturn  The hashtable.
 *
 * @since 2.4.0
 */
GHashTable *purple_chat_get_components(PurpleChat *chat);

/**
 * Returns the group of which the buddy is a member.

 * Get the type of a given node.
 *
 * @param node The node.
 *
 * @return The type of the node.
 *
 * @since 2.1.0
 */
PurpleBlistNodeType purple_blist_node_get_type(PurpleBlistNode *node);

/*@}*/

32687:02a2e8183b1d

{
	PURPLE_BLIST_NODE_FLAG_NO_SAVE      = 1 << 0 /**< node should not be saved with the buddy list */

} PurpleBlistNodeFlags;

#define PURPLE_BLIST_NODE(obj) ((PurpleBlistNode *)(obj))

#define PURPLE_BLIST_NODE_HAS_FLAG(b, f) (purple_blist_node_get_flags((PurpleBlistNode*)(b)) & (f))
#define PURPLE_BLIST_NODE_SHOULD_SAVE(b) (! PURPLE_BLIST_NODE_HAS_FLAG(b, PURPLE_BLIST_NODE_FLAG_NO_SAVE))

#define PURPLE_BLIST_NODE_NAME(n) (purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE  ? purple_chat_get_name((PurpleChat*)n) :        \
				     purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE ? purple_buddy_get_name((PurpleBuddy*)n) : NULL)

#define PURPLE_GROUP(obj) ((PurpleGroup *)(obj))

#define PURPLE_CONTACT(obj) ((PurpleContact *)(obj))

#define PURPLE_BUDDY(obj) ((PurpleBuddy *)(obj))

#define PURPLE_CHAT(obj) ((PurpleChat *)(obj))

#include "account.h"
#include "buddyicon.h"
#include "media.h"

	 * Implementation of this UI op is OPTIONAL. If not implemented, it will
	 * be set to a fallback function that saves data to blist.xml like in
	 * previous libpurple versions.
	 *
	 * @param node    The node which has been modified.
	 */
	void (*save_node)(PurpleBlistNode *node);

	/**
	 * Called when a node is about to be removed from the buddy list.

	 * Implementation of this UI op is OPTIONAL. If not implemented, it will
	 * be set to a fallback function that saves data to blist.xml like in
	 * previous libpurple versions.
	 *
	 * @param node  The node which has been modified.
	 */
	void (*remove_node)(PurpleBlistNode *node);

	/**
	 * Called to save all the data for an account. If the UI sets this,

	 * be set to a fallback function that saves data to blist.xml like in
	 * previous libpurple versions.
	 *
	 * @param account  The account whose data to save. If NULL, save all data
	 *                  for all accounts.
	 */
	void (*save_account)(PurpleAccount *account);

	void (*_purple_reserved1)(void);
};

 *
 * @return A list of every buddy in the list. Caller is responsible for
 *         freeing the list.
 *
 * @see purple_find_buddies
 */
GSList *purple_blist_get_buddies(void);

/**
 * Returns the UI data for the list.
 *
 * @return The UI data for the list.
 */
gpointer purple_blist_get_ui_data(void);

/**
 * Sets the UI data for the list.
 *
 * @param ui_data The UI data for the list.
 */
void purple_blist_set_ui_data(gpointer ui_data);

/**
 * Returns the next node of a given node. This function is to be used to iterate

/**
 * Returns the parent node of a given node.
 *
 * @param node A node.
 * @return  The parent node.
 *
 * @see purple_blist_node_get_first_child
 * @see purple_blist_node_get_sibling_next
 * @see purple_blist_node_get_sibling_prev
 * @see purple_blist_node_next
 */

/**
 * Returns the the first child node of a given node.
 *
 * @param node A node.
 * @return  The child node.
 *
 * @see purple_blist_node_get_parent
 * @see purple_blist_node_get_sibling_next
 * @see purple_blist_node_get_sibling_prev
 * @see purple_blist_node_next
 */

/**
 * Returns the sibling node of a given node.
 *
 * @param node A node.
 * @return  The sibling node.
 *
 * @see purple_blist_node_get_parent
 * @see purple_blist_node_get_first_child
 * @see purple_blist_node_get_sibling_prev
 * @see purple_blist_node_next
 */

/**
 * Returns the previous sibling node of a given node.
 *
 * @param node A node.
 * @return  The sibling node.
 *
 * @see purple_blist_node_get_parent
 * @see purple_blist_node_get_first_child
 * @see purple_blist_node_get_sibling_next
 * @see purple_blist_node_next
 */

/**
 * Returns the UI data of a given node.
 *
 * @param node The node.
 * @return The UI data.
 */
gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node);

/**
 * Sets the UI data of a given node.
 *
 * @param node The node.
 * @param ui_data The UI data.
 */
void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data);

/**
 * Shows the buddy list, creating a new one if necessary.

 *
 * @param buddy The buddy.
 * @return      The protocol data.
 *
 * @see purple_buddy_set_protocol_data()
 */
gpointer purple_buddy_get_protocol_data(const PurpleBuddy *buddy);

/**
 * Sets a buddy's protocol-specific data.

 *
 * @param buddy The buddy.
 * @param data  The data.
 *
 * @see purple_buddy_get_protocol_data()
 */
void purple_buddy_set_protocol_data(PurpleBuddy *buddy, gpointer data);

/**
 * Returns a buddy's contact.

/**
 * Gets the media caps from a buddy.
 *
 * @param buddy The buddy.
 * @return      The media caps.
 */
PurpleMediaCaps purple_buddy_get_media_caps(const PurpleBuddy *buddy);

/**
 * Sets the media caps for a buddy.

/**
 * Gets the PurpleGroup from a PurpleContact
 *
 * @param contact  The contact
 * @return         The group
 */
PurpleGroup *purple_contact_get_group(const PurpleContact *contact);

/**
 * Adds a new contact to the buddy list.

/**
 * Returns the local alias for the buddy, or @c NULL if none exists.
 *
 * @param buddy  The buddy
 * @return       The local alias for the buddy
 */
const char *purple_buddy_get_local_buddy_alias(PurpleBuddy *buddy);

/**
 * Returns the correct name to display for a blist chat.

 * Returns the account the chat belongs to.
 *
 * @param chat  The chat.
 *
 * @return  The account the chat belongs to.
 */
PurpleAccount *purple_chat_get_account(PurpleChat *chat);

/**
 * Get a hashtable containing information about a chat.
 *
 * @param chat  The chat.
 *
 * @constreturn  The hashtable.
 */
GHashTable *purple_chat_get_components(PurpleChat *chat);

/**
 * Returns the group of which the buddy is a member.

 * Get the type of a given node.
 *
 * @param node The node.
 *
 * @return The type of the node.
 */
PurpleBlistNodeType purple_blist_node_get_type(PurpleBlistNode *node);

/*@}*/