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