libpurple/buddylist.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_BUDDY_LIST_H
  23 #define PURPLE_BUDDY_LIST_H
  24
  25 /**
  26  * SECTION:buddylist
  27  * @section_id: libpurple-buddylist
  28  * @short_description: <filename>buddylist.h</filename>
  29  * @title: Buddy List API
  30  * @see_also: <link linkend="chapter-signals-blist">Buddy List signals</link>
  31  */
  32
  33 /* I can't believe I let ChipX86 inspire me to write good code. -Sean */
  34
  35 #include "buddy.h"
  36
  37 #define PURPLE_TYPE_BUDDY_LIST (purple_buddy_list_get_type())
  38 typedef struct _PurpleBuddyList PurpleBuddyList;
  39
  40 #define PURPLE_BLIST_DEFAULT_GROUP_NAME _("Buddies")
  41
  42 #include "chat.h"
  43
  44 /**
  45  * PurpleBlistWalkFunc:
  46  * @node: The node that's being iterated
  47  * @data: User supplied data.
  48  *
  49  * A callback function for purple_blist_walk.
  50  *
  51  * Since: 3.0.0
  52  */
  53 typedef void (*PurpleBlistWalkFunc)(PurpleBlistNode *node, gpointer data);
  54
  55 /**************************************************************************/
  56 /* Data Structures                                                        */
  57 /**************************************************************************/
  58 /**
  59  * PurpleBuddyList:
  60  *
  61  * The Buddy List
  62  */
  63 /**
  64  * PurpleBuddyListClass:
  65  * @new_node:     Sets UI-specific data on a node.
  66  * @show:         The core will call this when it's finished doing its core
  67  *                stuff.
  68  * @update:       This will update a node in the buddy list.
  69  * @remove:       This removes a node from the list
  70  * @set_visible:  Hides or unhides the buddy list.
  71  * @save_node:    This is called when a node has been modified and should be
  72  *                saved.
  73  *                <sbr/>Implementation of this method is
  74  *                <emphasis>OPTIONAL</emphasis>. If not implemented, it will be
  75  *                set to a fallback function that saves data to
  76  *                <filename>blist.xml</filename> like in previous libpurple
  77  *                versions.
  78  *                <sbr/>@node: The node which has been modified.
  79  * @remove_node:  Called when a node is about to be removed from the buddy list.
  80  *                The method should update the relevant data structures to
  81  *                remove this node (for example, removing a buddy from the
  82  *                group this node is in).
  83  *                <sbr/>Implementation of this method is
  84  *                <emphasis>OPTIONAL</emphasis>. If not implemented, it will be
  85  *                set to a fallback function that saves data to
  86  *                <filename>blist.xml</filename> like in previous libpurple
  87  *                versions.
  88  *                <sbr/>@node: The node which has been modified.
  89  * @save_account: Called to save all the data for an account. If the UI sets
  90  *                this, the callback must save the privacy and buddy list data
  91  *                for an account. If the account is %NULL, save the data for all
  92  *                accounts.
  93  *                <sbr/>Implementation of this method is
  94  *                <emphasis>OPTIONAL</emphasis>. If not implemented, it will be
  95  *                set to a fallback function that saves data to
  96  *                <filename>blist.xml</filename> like in previous
  97  *                libpurple versions.
  98  *                <sbr/>@account: The account whose data to save. If %NULL,
  99  *                                save all data for all accounts.
 100  *
 101  * Buddy list operations.
 102  *
 103  * Any UI representing a buddy list must derive a filled-out
 104  * @PurpleBuddyListClass and set the GType using purple_blist_set_ui() before a
 105  * buddy list is created.
 106  */
 107 struct _PurpleBuddyListClass {
 108         /*< private >*/
 109         GObjectClass gparent_class;
 110
 111         /*< public >*/
 112         void (*new_node)(PurpleBuddyList *list, PurpleBlistNode *node);
 113         void (*show)(PurpleBuddyList *list);
 114         void (*update)(PurpleBuddyList *list, PurpleBlistNode *node);
 115         void (*remove)(PurpleBuddyList *list, PurpleBlistNode *node);
 116         void (*set_visible)(PurpleBuddyList *list, gboolean show);
 117
 118         void (*request_add_buddy)(PurpleBuddyList *list, PurpleAccount *account,
 119                                   const char *username, const char *group,
 120                                   const char *alias);
 121
 122         void (*request_add_chat)(PurpleBuddyList *list, PurpleAccount *account,
 123                                  PurpleGroup *group, const char *alias,
 124                                  const char *name);
 125
 126         void (*request_add_group)(PurpleBuddyList *list);
 127
 128         void (*save_node)(PurpleBuddyList *list, PurpleBlistNode *node);
 129         void (*remove_node)(PurpleBuddyList *list, PurpleBlistNode *node);
 130
 131         void (*save_account)(PurpleBuddyList *list, PurpleAccount *account);
 132
 133         /*< private >*/
 134         gpointer reserved[4];
 135 };
 136
 137 G_BEGIN_DECLS
 138
 139 /**************************************************************************/
 140 /* Buddy List API                                                         */
 141 /**************************************************************************/
 142
 143 /**
 144  * purple_buddy_list_get_type:
 145  *
 146  * Returns: The #GType for the #PurpleBuddyList object.
 147  */
 148 G_DECLARE_DERIVABLE_TYPE(PurpleBuddyList, purple_buddy_list, PURPLE, BUDDY_LIST,
 149                          GObject)
 150
 151 /**
 152  * purple_blist_get_default:
 153  *
 154  * Returns the default buddy list.
 155  *
 156  * Returns: (transfer none): The default buddy list.
 157  *
 158  * Since: 3.0.0
 159  */
 160 PurpleBuddyList *purple_blist_get_default(void);
 161
 162 /**
 163  * purple_blist_get_default_root:
 164  *
 165  * Returns the root node of the default buddy list.
 166  *
 167  * Returns: (transfer none): The root node.
 168  *
 169  * Since: 3.0.0
 170  */
 171 PurpleBlistNode *purple_blist_get_default_root(void);
 172
 173 /**
 174  * purple_blist_get_root:
 175  * @list: The buddy list to query.
 176  *
 177  * Returns the root node of the specified buddy list.
 178  *
 179  * Returns: (transfer none): The root node.
 180  */
 181 PurpleBlistNode *purple_blist_get_root(PurpleBuddyList *list);
 182
 183 /**
 184  * purple_blist_get_buddies:
 185  *
 186  * Returns a list of every buddy in the list.  Use of this function is
 187  * discouraged if you do not actually need every buddy in the list.  Use
 188  * purple_blist_find_buddies instead.
 189  *
 190  * See purple_blist_find_buddies().
 191  *
 192  * Returns: (element-type PurpleBlistNode) (transfer container): A list of every
 193  *          buddy in the list.
 194  */
 195 GSList *purple_blist_get_buddies(void);
 196
 197 /**
 198  * purple_blist_show:
 199  *
 200  * Shows the buddy list, creating a new one if necessary.
 201  */
 202 void purple_blist_show(void);
 203
 204 /**
 205  * purple_blist_set_visible:
 206  * @show:   Whether or not to show the buddy list
 207  *
 208  * Hides or unhides the buddy list.
 209  */
 210 void purple_blist_set_visible(gboolean show);
 211
 212 /**
 213  * purple_blist_update_buddies_cache:
 214  * @buddy:    The buddy whose name will be changed.
 215  * @new_name: The new name of the buddy.
 216  *
 217  * Updates the buddies hash table when a buddy has been renamed. This only
 218  * updates the cache, the caller is responsible for the actual renaming of
 219  * the buddy after updating the cache.
 220  */
 221 void purple_blist_update_buddies_cache(PurpleBuddy *buddy, const char *new_name);
 222
 223 /**
 224  * purple_blist_update_groups_cache:
 225  * @group:    The group whose name will be changed.
 226  * @new_name: The new name of the group.
 227  *
 228  * Updates the groups hash table when a group has been renamed. This only
 229  * updates the cache, the caller is responsible for the actual renaming of
 230  * the group after updating the cache.
 231  */
 232 void purple_blist_update_groups_cache(PurpleGroup *group, const char *new_name);
 233
 234 /**
 235  * purple_blist_add_chat:
 236  * @chat:  The new chat who gets added
 237  * @group:  The group to add the new chat to.
 238  * @node:   The insertion point
 239  *
 240  * Adds a new chat to the buddy list.
 241  *
 242  * The chat will be inserted right after node or appended to the end
 243  * of group if node is NULL.  If both are NULL, the buddy will be added to
 244  * the "Chats" group.
 245  */
 246 void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node);
 247
 248 /**
 249  * purple_blist_add_buddy:
 250  * @buddy:   The new buddy who gets added
 251  * @contact: The optional contact to place the buddy in.
 252  * @group:   The group to add the new buddy to.
 253  * @node:    The insertion point.  Pass in NULL to add the node as
 254  *                the first child in the given group.
 255  *
 256  * Adds a new buddy to the buddy list.
 257  *
 258  * The buddy will be inserted right after node or prepended to the
 259  * group if node is NULL.  If both are NULL, the buddy will be added to
 260  * the default group.
 261  */
 262 void purple_blist_add_buddy(PurpleBuddy *buddy, PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node);
 263
 264 /**
 265  * purple_blist_add_group:
 266  * @group:  The group
 267  * @node:   The insertion point
 268  *
 269  * Adds a new group to the buddy list.
 270  *
 271  * The new group will be inserted after insert or prepended to the list if
 272  * node is NULL.
 273  */
 274 void purple_blist_add_group(PurpleGroup *group, PurpleBlistNode *node);
 275
 276 /**
 277  * purple_blist_add_contact:
 278  * @contact: The contact
 279  * @group:   The group to add the contact to
 280  * @node:    The insertion point
 281  *
 282  * Adds a new contact to the buddy list.
 283  *
 284  * The new contact will be inserted after insert or prepended to the list if
 285  * node is NULL.
 286  */
 287 void purple_blist_add_contact(PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node);
 288
 289 /**
 290  * purple_blist_remove_buddy:
 291  * @buddy:   The buddy to be removed
 292  *
 293  * Removes a buddy from the buddy list and frees the memory allocated to it.
 294  * This doesn't actually try to remove the buddy from the server list.
 295  *
 296  * See purple_account_remove_buddy().
 297  */
 298 void purple_blist_remove_buddy(PurpleBuddy *buddy);
 299
 300 /**
 301  * purple_blist_remove_contact:
 302  * @contact: The contact to be removed
 303  *
 304  * Removes a contact, and any buddies it contains, and frees the memory
 305  * allocated to it. This calls purple_blist_remove_buddy and therefore
 306  * doesn't remove the buddies from the server list.
 307  *
 308  * See purple_blist_remove_buddy().
 309  */
 310 void purple_blist_remove_contact(PurpleContact *contact);
 311
 312 /**
 313  * purple_blist_remove_chat:
 314  * @chat:   The chat to be removed
 315  *
 316  * Removes a chat from the buddy list and frees the memory allocated to it.
 317  */
 318 void purple_blist_remove_chat(PurpleChat *chat);
 319
 320 /**
 321  * purple_blist_remove_group:
 322  * @group:   The group to be removed
 323  *
 324  * Removes a group from the buddy list and frees the memory allocated to it and to
 325  * its children
 326  */
 327 void purple_blist_remove_group(PurpleGroup *group);
 328
 329 /**
 330  * purple_blist_find_buddy:
 331  * @account: The account this buddy belongs to
 332  * @name:    The buddy's name
 333  *
 334  * Finds the buddy struct given a name and an account
 335  *
 336  * Returns: (transfer none): The buddy or %NULL if the buddy does not exist.
 337  */
 338 PurpleBuddy *purple_blist_find_buddy(PurpleAccount *account, const char *name);
 339
 340 /**
 341  * purple_blist_find_buddy_in_group:
 342  * @account: The account this buddy belongs to
 343  * @name:    The buddy's name
 344  * @group:   The group to look in
 345  *
 346  * Finds the buddy struct given a name, an account, and a group
 347  *
 348  * Returns: (transfer none): The buddy or %NULL if the buddy does not exist in
 349  *          the group.
 350  */
 351 PurpleBuddy *purple_blist_find_buddy_in_group(PurpleAccount *account, const char *name,
 352                 PurpleGroup *group);
 353
 354 /**
 355  * purple_blist_find_buddies:
 356  * @account: The account this buddy belongs to
 357  * @name:    The buddy's name (or NULL to return all buddies for the account)
 358  *
 359  * Finds all PurpleBuddy structs given a name and an account
 360  *
 361  * Returns: (element-type PurpleBuddy) (transfer container): %NULL if the buddy
 362  *          doesn't exist, or a GSList of PurpleBuddy structs.
 363  */
 364 GSList *purple_blist_find_buddies(PurpleAccount *account, const char *name);
 365
 366 /**
 367  * purple_blist_find_group:
 368  * @name:    The group's name
 369  *
 370  * Finds a group by name
 371  *
 372  * Returns: (transfer none): The group or %NULL if the group does not exist.
 373  */
 374 PurpleGroup *purple_blist_find_group(const char *name);
 375
 376 /**
 377  * purple_blist_get_default_group:
 378  *
 379  * Finds or creates default group.
 380  *
 381  * Returns: (transfer none): The default group.
 382  */
 383 PurpleGroup *purple_blist_get_default_group(void);
 384
 385 /**
 386  * purple_blist_find_chat:
 387  * @account: The chat's account.
 388  * @name:    The chat's name.
 389  *
 390  * Finds a chat by name.
 391  *
 392  * Returns: (transfer none): The chat, or %NULL if the chat does not exist.
 393  */
 394 PurpleChat *purple_blist_find_chat(PurpleAccount *account, const char *name);
 395
 396 /**
 397  * purple_blist_add_account:
 398  * @account:   The account
 399  *
 400  * Called when an account connects.  Tells the UI to update all the
 401  * buddies.
 402  */
 403 void purple_blist_add_account(PurpleAccount *account);
 404
 405 /**
 406  * purple_blist_remove_account:
 407  * @account:   The account
 408  *
 409  * Called when an account disconnects.  Sets the presence of all the buddies to 0
 410  * and tells the UI to update them.
 411  */
 412 void purple_blist_remove_account(PurpleAccount *account);
 413
 414 /**
 415  * purple_blist_walk:
 416  * @group_func: (scope call): The callback for groups
 417  * @chat_func: (scope call): The callback for chats
 418  * @meta_contact_func: (scope call): The callback for meta-contacts
 419  * @contact_func: (scope call): The callback for contacts
 420  * @data: User supplied data.
 421  *
 422  * Walks the buddy list and calls the appropriate function for each node.  If
 423  * a callback function is omitted iteration will continue without it.
 424  *
 425  * Since: 3.0.0
 426  */
 427 void purple_blist_walk(PurpleBlistWalkFunc group_func, PurpleBlistWalkFunc chat_func, PurpleBlistWalkFunc meta_contact_func, PurpleBlistWalkFunc contact_func, gpointer data);
 428
 429 /****************************************************************************************/
 430 /* Buddy list file management API                                                       */
 431 /****************************************************************************************/
 432
 433 /**
 434  * purple_blist_schedule_save:
 435  *
 436  * Schedule a save of the <filename>blist.xml</filename> file.  This is used by
 437  * the account API whenever the privacy settings are changed.  If you make a
 438  * change to <filename>blist.xml</filename> using one of the functions in the
 439  * buddy list API, then the buddy list is saved automatically, so you should not
 440  * need to call this.
 441  */
 442 void purple_blist_schedule_save(void);
 443
 444 /**
 445  * purple_blist_request_add_buddy:
 446  * @account:  The account the buddy is added to.
 447  * @username: The username of the buddy.
 448  * @group:    The name of the group to place the buddy in.
 449  * @alias:    The optional alias for the buddy.
 450  *
 451  * Requests from the user information needed to add a buddy to the
 452  * buddy list.
 453  */
 454 void purple_blist_request_add_buddy(PurpleAccount *account, const char *username,
 455                                                                   const char *group, const char *alias);
 456
 457 /**
 458  * purple_blist_request_add_chat:
 459  * @account: The account the buddy is added to.
 460  * @group:   The optional group to add the chat to.
 461  * @alias:   The optional alias for the chat.
 462  * @name:    The required chat name.
 463  *
 464  * Requests from the user information needed to add a chat to the
 465  * buddy list.
 466  */
 467 void purple_blist_request_add_chat(PurpleAccount *account, PurpleGroup *group,
 468                                                                  const char *alias, const char *name);
 469
 470 /**
 471  * purple_blist_request_add_group:
 472  *
 473  * Requests from the user information needed to add a group to the
 474  * buddy list.
 475  */
 476 void purple_blist_request_add_group(void);
 477
 478 /**
 479  * purple_blist_new_node:
 480  * @list: The list that contains the node.
 481  * @node: The node to initialize.
 482  *
 483  * Sets UI-specific data on a node.
 484  *
 485  * This should usually only be run when initializing a @PurpleBlistNode
 486  * instance.
 487  *
 488  * Since: 3.0.0
 489  */
 490 void purple_blist_new_node(PurpleBuddyList *list, PurpleBlistNode *node);
 491
 492 /**
 493  * purple_blist_update_node:
 494  * @list: The buddy list to modify.
 495  * @node: The node to update.
 496  *
 497  * Update a node in the buddy list in the UI.
 498  *
 499  * Since: 3.0.0
 500  */
 501 void purple_blist_update_node(PurpleBuddyList *list, PurpleBlistNode *node);
 502
 503 /**
 504  * purple_blist_save_node:
 505  * @list: The list that contains the node.
 506  * @node: The node which has been modified.
 507  *
 508  * This is called when a node has been modified and should be saved by the UI.
 509  *
 510  * If the UI does not implement a more specific method, it will be set to save
 511  * data to <filename>blist.xml</filename> like in previous libpurple versions.
 512  *
 513  * Since: 3.0.0
 514  */
 515 void purple_blist_save_node(PurpleBuddyList *list, PurpleBlistNode *node);
 516
 517 /**
 518  * purple_blist_save_account:
 519  * @list: The list that contains the account.
 520  * @account: The account whose data to save. If %NULL, save all data for all
 521  *           accounts.
 522  *
 523  * Save all the data for an account.
 524  *
 525  * If the UI does not set a more specific method, it will be set to save data
 526  * to <filename>blist.xml</filename> like in previous libpurple versions.
 527  *
 528  * Since: 3.0.0
 529  */
 530 void purple_blist_save_account(PurpleBuddyList *list, PurpleAccount *account);
 531
 532 /**************************************************************************/
 533 /* Buddy List Subsystem                                                   */
 534 /**************************************************************************/
 535
 536 /**
 537  * purple_blist_set_ui:
 538  * @type: The @GType of a derived UI implementation of @PurpleBuddyList.
 539  *
 540  * Set the UI implementation of the buddy list.
 541  *
 542  * This must be called before the buddy list is created or you will get the
 543  * default libpurple implementation.
 544  *
 545  * Since: 3.0.0
 546  */
 547 void purple_blist_set_ui(GType type);
 548
 549 /**
 550  * purple_blist_get_handle:
 551  *
 552  * Returns the handle for the buddy list subsystem.
 553  *
 554  * Returns: The buddy list subsystem handle.
 555  */
 556 void *purple_blist_get_handle(void);
 557
 558 /**
 559  * purple_blist_init:
 560  *
 561  * Initializes the buddy list subsystem.
 562  */
 563 void purple_blist_init(void);
 564
 565 /**
 566  * purple_blist_boot:
 567  *
 568  * Loads the buddy list.
 569  *
 570  * You shouldn't call this. purple_core_init() will do it for you.
 571  */
 572 void purple_blist_boot(void);
 573
 574 /**
 575  * purple_blist_uninit:
 576  *
 577  * Uninitializes the buddy list subsystem.
 578  */
 579 void purple_blist_uninit(void);
 580
 581 G_END_DECLS
 582
 583 #endif /* PURPLE_BUDDY_LIST_H */