libpurple/blistnode.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_BLIST_NODE_H
  23 #define PURPLE_BLIST_NODE_H
  24 /**
  25  * SECTION:blistnode
  26  * @section_id: libpurple-blistnode
  27  * @short_description: <filename>blistnode.h</filename>
  28  * @title: Buddy List Node and Counting Node types
  29  */
  30
  31 #include <glib.h>
  32 #include <glib-object.h>
  33
  34 #define PURPLE_TYPE_BLIST_NODE             (purple_blist_node_get_type())
  35 #define PURPLE_BLIST_NODE(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_BLIST_NODE, PurpleBlistNode))
  36 #define PURPLE_BLIST_NODE_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_BLIST_NODE, PurpleBlistNodeClass))
  37 #define PURPLE_IS_BLIST_NODE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_BLIST_NODE))
  38 #define PURPLE_IS_BLIST_NODE_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_BLIST_NODE))
  39 #define PURPLE_BLIST_NODE_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_BLIST_NODE, PurpleBlistNodeClass))
  40
  41 typedef struct _PurpleBlistNode PurpleBlistNode;
  42 typedef struct _PurpleBlistNodeClass PurpleBlistNodeClass;
  43
  44 /**
  45  * PurpleBlistNode:
  46  * @prev:    The sibling before this buddy.
  47  * @next:    The sibling after this buddy.
  48  * @parent:  The parent of this node.
  49  * @child:   The child of this node.
  50  * @ui_data: The UI data associated with this node. This is a convenience
  51  *           field provided to the UIs -- it is not used by the libpurple core.
  52  *
  53  * A Buddy list node.  This can represent a group, a buddy, or anything else.
  54  * This is a base class for PurpleBuddy, PurpleContact, PurpleGroup, and for
  55  * anything else that wants to put itself in the buddy list.
  56  */
  57 struct _PurpleBlistNode {
  58         GObject gparent;
  59
  60         /*< public >*/
  61         PurpleBlistNode *prev;
  62         PurpleBlistNode *next;
  63         PurpleBlistNode *parent;
  64         PurpleBlistNode *child;
  65
  66         gpointer ui_data;
  67 };
  68
  69 struct _PurpleBlistNodeClass {
  70         GObjectClass gparent_class;
  71
  72         /*< private >*/
  73         void (*_purple_reserved1)(void);
  74         void (*_purple_reserved2)(void);
  75         void (*_purple_reserved3)(void);
  76         void (*_purple_reserved4)(void);
  77 };
  78
  79 G_BEGIN_DECLS
  80
  81 /**
  82  * purple_blist_node_get_type:
  83  *
  84  * Returns: The #GType for the #PurpleBlistNode object.
  85  */
  86 GType purple_blist_node_get_type(void);
  87
  88 /**
  89  * purple_blist_node_next:
  90  * @node:               A node.
  91  * @offline:    Whether to include nodes for offline accounts
  92  *
  93  * Returns the next node of a given node. This function is to be used to iterate
  94  * over the tree returned by purple_blist_get_buddy_list.
  95  *
  96  * See purple_blist_node_get_parent(), purple_blist_node_get_first_child(),
  97  *   purple_blist_node_get_sibling_next(), purple_blist_node_get_sibling_prev().
  98  *
  99  * Returns:     The next node
 100  */
 101 PurpleBlistNode *purple_blist_node_next(PurpleBlistNode *node, gboolean offline);
 102
 103 /**
 104  * purple_blist_node_get_parent:
 105  * @node: A node.
 106  *
 107  * Returns the parent node of a given node.
 108  *
 109  * See purple_blist_node_get_first_child(), purple_blist_node_get_sibling_next(),
 110  *     purple_blist_node_get_sibling_prev(), purple_blist_node_next().
 111  *
 112  * Returns:  The parent node.
 113  */
 114 PurpleBlistNode *purple_blist_node_get_parent(PurpleBlistNode *node);
 115
 116 /**
 117  * purple_blist_node_get_first_child:
 118  * @node: A node.
 119  *
 120  * Returns the the first child node of a given node.
 121  *
 122  * See purple_blist_node_get_parent(), purple_blist_node_get_sibling_next(),
 123  *     purple_blist_node_get_sibling_prev(), purple_blist_node_next().
 124  *
 125  * Returns:  The child node.
 126  */
 127 PurpleBlistNode *purple_blist_node_get_first_child(PurpleBlistNode *node);
 128
 129 /**
 130  * purple_blist_node_get_sibling_next:
 131  * @node: A node.
 132  *
 133  * Returns the sibling node of a given node.
 134  *
 135  * See purple_blist_node_get_parent(), purple_blist_node_get_first_child(),
 136  *     purple_blist_node_get_sibling_prev(), purple_blist_node_next().
 137  *
 138  * Returns:  The sibling node.
 139  */
 140 PurpleBlistNode *purple_blist_node_get_sibling_next(PurpleBlistNode *node);
 141
 142 /**
 143  * purple_blist_node_get_sibling_prev:
 144  * @node: A node.
 145  *
 146  * Returns the previous sibling node of a given node.
 147  *
 148  * See purple_blist_node_get_parent(), purple_blist_node_get_first_child(),
 149  *     purple_blist_node_get_sibling_next(), purple_blist_node_next().
 150  *
 151  * Returns:  The sibling node.
 152  */
 153 PurpleBlistNode *purple_blist_node_get_sibling_prev(PurpleBlistNode *node);
 154
 155 /**
 156  * purple_blist_node_get_ui_data:
 157  * @node: The node.
 158  *
 159  * Returns the UI data of a given node.
 160  *
 161  * Returns: The UI data.
 162  */
 163 gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node);
 164
 165 /**
 166  * purple_blist_node_set_ui_data:
 167  * @node: The node.
 168  * @ui_data: The UI data.
 169  *
 170  * Sets the UI data of a given node.
 171  */
 172 void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data);
 173
 174 /**
 175  * purple_blist_node_get_settings:
 176  * @node:  The node to from which to get settings
 177  *
 178  * Returns a node's settings
 179  *
 180  * Returns: The hash table with the node's settings
 181  */
 182 GHashTable *purple_blist_node_get_settings(PurpleBlistNode *node);
 183
 184 /**
 185  * purple_blist_node_has_setting:
 186  * @node:  The node to check from which to check settings
 187  * @key:   The identifier of the data
 188  *
 189  * Checks whether a named setting exists for a node in the buddy list
 190  *
 191  * Returns: TRUE if a value exists, or FALSE if there is no setting
 192  */
 193 gboolean purple_blist_node_has_setting(PurpleBlistNode *node, const char *key);
 194
 195 /**
 196  * purple_blist_node_set_bool:
 197  * @node:  The node to associate the data with
 198  * @key:   The identifier for the data
 199  * @value: The value to set
 200  *
 201  * Associates a boolean with a node in the buddy list
 202  */
 203 void purple_blist_node_set_bool(PurpleBlistNode *node, const char *key, gboolean value);
 204
 205 /**
 206  * purple_blist_node_get_bool:
 207  * @node:  The node to retrieve the data from
 208  * @key:   The identifier of the data
 209  *
 210  * Retrieves a named boolean setting from a node in the buddy list
 211  *
 212  * Returns: The value, or FALSE if there is no setting
 213  */
 214 gboolean purple_blist_node_get_bool(PurpleBlistNode *node, const char *key);
 215
 216 /**
 217  * purple_blist_node_set_int:
 218  * @node:  The node to associate the data with
 219  * @key:   The identifier for the data
 220  * @value: The value to set
 221  *
 222  * Associates an integer with a node in the buddy list
 223  */
 224 void purple_blist_node_set_int(PurpleBlistNode *node, const char *key, int value);
 225
 226 /**
 227  * purple_blist_node_get_int:
 228  * @node:  The node to retrieve the data from
 229  * @key:   The identifier of the data
 230  *
 231  * Retrieves a named integer setting from a node in the buddy list
 232  *
 233  * Returns: The value, or 0 if there is no setting
 234  */
 235 int purple_blist_node_get_int(PurpleBlistNode *node, const char *key);
 236
 237 /**
 238  * purple_blist_node_set_string:
 239  * @node:  The node to associate the data with
 240  * @key:   The identifier for the data
 241  * @value: The value to set
 242  *
 243  * Associates a string with a node in the buddy list
 244  */
 245 void purple_blist_node_set_string(PurpleBlistNode *node, const char *key,
 246                 const char *value);
 247
 248 /**
 249  * purple_blist_node_get_string:
 250  * @node:  The node to retrieve the data from
 251  * @key:   The identifier of the data
 252  *
 253  * Retrieves a named string setting from a node in the buddy list
 254  *
 255  * Returns: The value, or NULL if there is no setting
 256  */
 257 const char *purple_blist_node_get_string(PurpleBlistNode *node, const char *key);
 258
 259 /**
 260  * purple_blist_node_remove_setting:
 261  * @node:  The node from which to remove the setting
 262  * @key:   The name of the setting
 263  *
 264  * Removes a named setting from a blist node
 265  */
 266 void purple_blist_node_remove_setting(PurpleBlistNode *node, const char *key);
 267
 268 /**
 269  * purple_blist_node_set_transient:
 270  * @node:  The node
 271  * @transient: TRUE if the node should NOT be saved, FALSE if node should
 272  *                  be saved
 273  *
 274  * Sets whether the node should be saved with the buddy list or not
 275  */
 276 void purple_blist_node_set_transient(PurpleBlistNode *node, gboolean transient);
 277
 278 /**
 279  * purple_blist_node_is_transient:
 280  * @node:  The node
 281  *
 282  * Gets whether the node should be saved with the buddy list or not
 283  *
 284  * Returns: TRUE if the node should NOT be saved, FALSE if node should be saved
 285  */
 286 gboolean purple_blist_node_is_transient(PurpleBlistNode *node);
 287
 288 /**
 289  * purple_blist_node_get_extended_menu:
 290  * @n: The blist node for which to obtain the extended menu items.
 291  *
 292  * Retrieves the extended menu items for a buddy list node.
 293  *
 294  * Returns:  A list of PurpleMenuAction items, as harvested by the
 295  *          blist-node-extended-menu signal.
 296  */
 297 GList *purple_blist_node_get_extended_menu(PurpleBlistNode *n);
 298
 299 G_END_DECLS
 300
 301 #endif /* PURPLE_BLIST_NODE_H */
 302