libpurple/account.h

   1 /**
   2  * @file account.h Account API
   3  * @ingroup core
   4  * @see @ref account-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27 #ifndef _PURPLE_ACCOUNT_H_
  28 #define _PURPLE_ACCOUNT_H_
  29
  30 #include <glib.h>
  31 #include <glib-object.h>
  32
  33 /** @copydoc _PurpleAccountUiOps */
  34 typedef struct _PurpleAccountUiOps PurpleAccountUiOps;
  35 /** @copydoc _PurpleAccount */
  36 typedef struct _PurpleAccount      PurpleAccount;
  37
  38 typedef gboolean (*PurpleFilterAccountFunc)(PurpleAccount *account);
  39 typedef void (*PurpleAccountRequestAuthorizationCb)(void *);
  40 typedef void (*PurpleAccountRegistrationCb)(PurpleAccount *account, gboolean succeeded, void *user_data);
  41 typedef void (*PurpleAccountUnregistrationCb)(PurpleAccount *account, gboolean succeeded, void *user_data);
  42
  43 #include "connection.h"
  44 #include "log.h"
  45 #include "privacy.h"
  46 #include "proxy.h"
  47 #include "prpl.h"
  48 #include "status.h"
  49
  50 /**
  51  * Account request types.
  52  */
  53 typedef enum
  54 {
  55         PURPLE_ACCOUNT_REQUEST_AUTHORIZATION = 0 /* Account authorization request */
  56 } PurpleAccountRequestType;
  57
  58
  59 /**  Account UI operations, used to notify the user of status changes and when
  60  *   buddies add this account to their buddy lists.
  61  */
  62 struct _PurpleAccountUiOps
  63 {
  64         /** A buddy who is already on this account's buddy list added this account
  65          *  to their buddy list.
  66          */
  67         void (*notify_added)(PurpleAccount *account,
  68                              const char *remote_user,
  69                              const char *id,
  70                              const char *alias,
  71                              const char *message);
  72
  73         /** This account's status changed. */
  74         void (*status_changed)(PurpleAccount *account,
  75                                PurpleStatus *status);
  76
  77         /** Someone we don't have on our list added us; prompt to add them. */
  78         void (*request_add)(PurpleAccount *account,
  79                             const char *remote_user,
  80                             const char *id,
  81                             const char *alias,
  82                             const char *message);
  83
  84         /** Prompt for authorization when someone adds this account to their buddy
  85          * list.  To authorize them to see this account's presence, call \a
  86          * authorize_cb (\a user_data); otherwise call \a deny_cb (\a user_data);
  87          * @return a UI-specific handle, as passed to #close_account_request.
  88          */
  89         void *(*request_authorize)(PurpleAccount *account,
  90                                    const char *remote_user,
  91                                    const char *id,
  92                                    const char *alias,
  93                                    const char *message,
  94                                    gboolean on_list,
  95                                    PurpleAccountRequestAuthorizationCb authorize_cb,
  96                                    PurpleAccountRequestAuthorizationCb deny_cb,
  97                                    void *user_data);
  98
  99         /** Close a pending request for authorization.  \a ui_handle is a handle
 100          *  as returned by #request_authorize.
 101          */
 102         void (*close_account_request)(void *ui_handle);
 103
 104         void (*_purple_reserved1)(void);
 105         void (*_purple_reserved2)(void);
 106         void (*_purple_reserved3)(void);
 107         void (*_purple_reserved4)(void);
 108 };
 109
 110 /** Structure representing an account.
 111  */
 112 struct _PurpleAccount
 113 {
 114         char *username;             /**< The username.                          */
 115         char *alias;                /**< How you appear to yourself.            */
 116         char *password;             /**< The account password.                  */
 117         char *user_info;            /**< User information.                      */
 118
 119         char *buddy_icon_path;      /**< The buddy icon's non-cached path.      */
 120
 121         gboolean remember_pass;     /**< Remember the password.                 */
 122
 123         char *protocol_id;          /**< The ID of the protocol.                */
 124
 125         PurpleConnection *gc;         /**< The connection handle.                 */
 126         gboolean disconnecting;     /**< The account is currently disconnecting */
 127
 128         GHashTable *settings;       /**< Protocol-specific settings.            */
 129         GHashTable *ui_settings;    /**< UI-specific settings.                  */
 130
 131         PurpleProxyInfo *proxy_info;  /**< Proxy information.  This will be set   */
 132                                                                 /*   to NULL when the account inherits      */
 133                                                                 /*   proxy settings from global prefs.      */
 134
 135         /*
 136          * TODO: Supplementing the next two linked lists with hash tables
 137          * should help performance a lot when these lists are long.  This
 138          * matters quite a bit for protocols like MSN, where all your
 139          * buddies are added to your permit list.  Currently we have to
 140          * iterate through the entire list if we want to check if someone
 141          * is permitted or denied.  We should do this for 3.0.0.
 142          */
 143         GSList *permit;             /**< Permit list.                           */
 144         GSList *deny;               /**< Deny list.                             */
 145         PurplePrivacyType perm_deny;  /**< The permit/deny setting.               */
 146
 147         GList *status_types;        /**< Status types.                          */
 148
 149         PurplePresence *presence;     /**< Presence.                              */
 150         PurpleLog *system_log;        /**< The system log                         */
 151
 152         void *ui_data;              /**< The UI can put data here.              */
 153         PurpleAccountRegistrationCb registration_cb;
 154         void *registration_cb_user_data;
 155
 156         gpointer priv;              /**< Pointer to opaque private data. */
 157 };
 158
 159 #ifdef __cplusplus
 160 extern "C" {
 161 #endif
 162
 163 /**************************************************************************/
 164 /** @name Account API                                                     */
 165 /**************************************************************************/
 166 /*@{*/
 167
 168 /**
 169  * Creates a new account.
 170  *
 171  * @param username    The username.
 172  * @param protocol_id The protocol ID.
 173  *
 174  * @return The new account.
 175  */
 176 PurpleAccount *purple_account_new(const char *username, const char *protocol_id);
 177
 178 /**
 179  * Destroys an account.
 180  *
 181  * @param account The account to destroy.
 182  */
 183 void purple_account_destroy(PurpleAccount *account);
 184
 185 /**
 186  * Connects to an account.
 187  *
 188  * @param account The account to connect to.
 189  */
 190 void purple_account_connect(PurpleAccount *account);
 191
 192 /**
 193  * Sets the callback for successful registration.
 194  *
 195  * @param account       The account for which this callback should be used
 196  * @param cb    The callback
 197  * @param user_data     The user data passed to the callback
 198  */
 199 void purple_account_set_register_callback(PurpleAccount *account, PurpleAccountRegistrationCb cb, void *user_data);
 200
 201 /**
 202  * Registers an account.
 203  *
 204  * @param account The account to register.
 205  */
 206 void purple_account_register(PurpleAccount *account);
 207
 208 /**
 209  * Unregisters an account (deleting it from the server).
 210  *
 211  * @param account The account to unregister.
 212  * @param cb Optional callback to be called when unregistration is complete
 213  * @param user_data user data to pass to the callback
 214  */
 215 void purple_account_unregister(PurpleAccount *account, PurpleAccountUnregistrationCb cb, void *user_data);
 216
 217 /**
 218  * Disconnects from an account.
 219  *
 220  * @param account The account to disconnect from.
 221  */
 222 void purple_account_disconnect(PurpleAccount *account);
 223
 224 /**
 225  * Notifies the user that the account was added to a remote user's
 226  * buddy list.
 227  *
 228  * This will present a dialog informing the user that he was added to the
 229  * remote user's buddy list.
 230  *
 231  * @param account     The account that was added.
 232  * @param remote_user The name of the user that added this account.
 233  * @param id          The optional ID of the local account. Rarely used.
 234  * @param alias       The optional alias of the user.
 235  * @param message     The optional message sent from the user adding you.
 236  */
 237 void purple_account_notify_added(PurpleAccount *account, const char *remote_user,
 238                                const char *id, const char *alias,
 239                                const char *message);
 240
 241 /**
 242  * Notifies the user that the account was addded to a remote user's buddy
 243  * list and asks ther user if they want to add the remote user to their buddy
 244  * list.
 245  *
 246  * This will present a dialog informing the local user that the remote user
 247  * added them to the remote user's buddy list and will ask if they want to add
 248  * the remote user to the buddy list.
 249  *
 250  * @param account     The account that was added.
 251  * @param remote_user The name of the user that added this account.
 252  * @param id          The optional ID of the local account. Rarely used.
 253  * @param alias       The optional alias of the user.
 254  * @param message     The optional message sent from the user adding you.
 255  */
 256 void purple_account_request_add(PurpleAccount *account, const char *remote_user,
 257                               const char *id, const char *alias,
 258                               const char *message);
 259
 260 /**
 261  * Notifies the user that a remote user has wants to add the local user
 262  * to his or her buddy list and requires authorization to do so.
 263  *
 264  * This will present a dialog informing the user of this and ask if the
 265  * user authorizes or denies the remote user from adding him.
 266  *
 267  * @param account      The account that was added
 268  * @param remote_user  The name of the user that added this account.
 269  * @param id           The optional ID of the local account. Rarely used.
 270  * @param alias        The optional alias of the remote user.
 271  * @param message      The optional message sent by the user wanting to add you.
 272  * @param on_list      Is the remote user already on the buddy list?
 273  * @param auth_cb      The callback called when the local user accepts
 274  * @param deny_cb      The callback called when the local user rejects
 275  * @param user_data    Data to be passed back to the above callbacks
 276  *
 277  * @return A UI-specific handle.
 278  */
 279 void *purple_account_request_authorization(PurpleAccount *account, const char *remote_user,
 280                                         const char *id, const char *alias, const char *message, gboolean on_list,
 281                                         PurpleAccountRequestAuthorizationCb auth_cb, PurpleAccountRequestAuthorizationCb deny_cb, void *user_data);
 282
 283 /**
 284  * Close account requests registered for the given PurpleAccount
 285  *
 286  * @param account          The account for which requests should be closed
 287  */
 288 void purple_account_request_close_with_account(PurpleAccount *account);
 289
 290 /**
 291  * Close the account request for the given ui handle
 292  *
 293  * @param ui_handle        The ui specific handle for which requests should be closed
 294  */
 295 void purple_account_request_close(void *ui_handle);
 296
 297 /**
 298  * Requests a password from the user for the account. Does not set the
 299  * account password on success; do that in ok_cb if desired.
 300  *
 301  * @param account     The account to request the password for.
 302  * @param ok_cb       The callback for the OK button.
 303  * @param cancel_cb   The callback for the cancel button.
 304  * @param user_data   User data to be passed into callbacks.
 305  */
 306 void purple_account_request_password(PurpleAccount *account, GCallback ok_cb,
 307                                      GCallback cancel_cb, void *user_data);
 308
 309 /**
 310  * Requests information from the user to change the account's password.
 311  *
 312  * @param account The account to change the password on.
 313  */
 314 void purple_account_request_change_password(PurpleAccount *account);
 315
 316 /**
 317  * Requests information from the user to change the account's
 318  * user information.
 319  *
 320  * @param account The account to change the user information on.
 321  */
 322 void purple_account_request_change_user_info(PurpleAccount *account);
 323
 324 /**
 325  * Sets the account's username.
 326  *
 327  * @param account  The account.
 328  * @param username The username.
 329  */
 330 void purple_account_set_username(PurpleAccount *account, const char *username);
 331
 332 /**
 333  * Sets the account's password.
 334  *
 335  * @param account  The account.
 336  * @param password The password.
 337  */
 338 void purple_account_set_password(PurpleAccount *account, const char *password);
 339
 340 /**
 341  * Sets the account's alias.
 342  *
 343  * @param account The account.
 344  * @param alias   The alias.
 345  */
 346 void purple_account_set_alias(PurpleAccount *account, const char *alias);
 347
 348 /**
 349  * Sets the account's user information
 350  *
 351  * @param account   The account.
 352  * @param user_info The user information.
 353  */
 354 void purple_account_set_user_info(PurpleAccount *account, const char *user_info);
 355
 356 /**
 357  * Sets the account's buddy icon path.
 358  *
 359  * @param account The account.
 360  * @param path    The buddy icon non-cached path.
 361  */
 362 void purple_account_set_buddy_icon_path(PurpleAccount *account, const char *path);
 363
 364 /**
 365  * Sets the account's protocol ID.
 366  *
 367  * @param account     The account.
 368  * @param protocol_id The protocol ID.
 369  */
 370 void purple_account_set_protocol_id(PurpleAccount *account,
 371                                                                   const char *protocol_id);
 372
 373 /**
 374  * Sets the account's connection.
 375  *
 376  * @param account The account.
 377  * @param gc      The connection.
 378  */
 379 void purple_account_set_connection(PurpleAccount *account, PurpleConnection *gc);
 380
 381 /**
 382  * Sets whether or not this account should save its password.
 383  *
 384  * @param account The account.
 385  * @param value   @c TRUE if it should remember the password.
 386  */
 387 void purple_account_set_remember_password(PurpleAccount *account, gboolean value);
 388
 389 /**
 390  * Sets whether or not this account should check for mail.
 391  *
 392  * @param account The account.
 393  * @param value   @c TRUE if it should check for mail.
 394  */
 395 void purple_account_set_check_mail(PurpleAccount *account, gboolean value);
 396
 397 /**
 398  * Sets whether or not this account is enabled for the specified
 399  * UI.
 400  *
 401  * @param account The account.
 402  * @param ui      The UI.
 403  * @param value   @c TRUE if it is enabled.
 404  */
 405 void purple_account_set_enabled(PurpleAccount *account, const char *ui,
 406                               gboolean value);
 407
 408 /**
 409  * Sets the account's proxy information.
 410  *
 411  * @param account The account.
 412  * @param info    The proxy information.
 413  */
 414 void purple_account_set_proxy_info(PurpleAccount *account, PurpleProxyInfo *info);
 415
 416 /**
 417  * Sets the account's status types.
 418  *
 419  * @param account      The account.
 420  * @param status_types The list of status types.
 421  */
 422 void purple_account_set_status_types(PurpleAccount *account, GList *status_types);
 423
 424 /**
 425  * Variadic version of purple_account_set_status_list(); the variadic list
 426  * replaces @a attrs, and should be <tt>NULL</tt>-terminated.
 427  *
 428  * @copydoc purple_account_set_status_list()
 429  */
 430 void purple_account_set_status(PurpleAccount *account, const char *status_id,
 431         gboolean active, ...) G_GNUC_NULL_TERMINATED;
 432
 433
 434 /**
 435  * Activates or deactivates a status.  All changes to the statuses of
 436  * an account go through this function or purple_account_set_status().
 437  *
 438  * You can only deactivate an exclusive status by activating another exclusive
 439  * status.  So, if @a status_id is an exclusive status and @a active is @c
 440  * FALSE, this function does nothing.
 441  *
 442  * @param account   The account.
 443  * @param status_id The ID of the status.
 444  * @param active    Whether @a status_id is to be activated (<tt>TRUE</tt>) or
 445  *                  deactivated (<tt>FALSE</tt>).
 446  * @param attrs     A list of <tt>const char *</tt> attribute names followed by
 447  *                  <tt>const char *</tt> attribute values for the status.
 448  *                  (For example, one pair might be <tt>"message"</tt> followed
 449  *                  by <tt>"hello, talk to me!"</tt>.)
 450  */
 451 void purple_account_set_status_list(PurpleAccount *account,
 452         const char *status_id, gboolean active, GList *attrs);
 453
 454 /**
 455  * Clears all protocol-specific settings on an account.
 456  *
 457  * @param account The account.
 458  */
 459 void purple_account_clear_settings(PurpleAccount *account);
 460
 461 /**
 462  * Removes an account-specific setting by name.
 463  *
 464  * @param account The account.
 465  * @param setting The setting to remove.
 466  *
 467  * @since 2.6.0
 468  */
 469 void purple_account_remove_setting(PurpleAccount *account, const char *setting);
 470
 471 /**
 472  * Sets a protocol-specific integer setting for an account.
 473  *
 474  * @param account The account.
 475  * @param name    The name of the setting.
 476  * @param value   The setting's value.
 477  */
 478 void purple_account_set_int(PurpleAccount *account, const char *name, int value);
 479
 480 /**
 481  * Sets a protocol-specific string setting for an account.
 482  *
 483  * @param account The account.
 484  * @param name    The name of the setting.
 485  * @param value   The setting's value.
 486  */
 487 void purple_account_set_string(PurpleAccount *account, const char *name,
 488                                                          const char *value);
 489
 490 /**
 491  * Sets a protocol-specific boolean setting for an account.
 492  *
 493  * @param account The account.
 494  * @param name    The name of the setting.
 495  * @param value   The setting's value.
 496  */
 497 void purple_account_set_bool(PurpleAccount *account, const char *name,
 498                                                    gboolean value);
 499
 500 /**
 501  * Sets a UI-specific integer setting for an account.
 502  *
 503  * @param account The account.
 504  * @param ui      The UI name.
 505  * @param name    The name of the setting.
 506  * @param value   The setting's value.
 507  */
 508 void purple_account_set_ui_int(PurpleAccount *account, const char *ui,
 509                                                          const char *name, int value);
 510
 511 /**
 512  * Sets a UI-specific string setting for an account.
 513  *
 514  * @param account The account.
 515  * @param ui      The UI name.
 516  * @param name    The name of the setting.
 517  * @param value   The setting's value.
 518  */
 519 void purple_account_set_ui_string(PurpleAccount *account, const char *ui,
 520                                                                 const char *name, const char *value);
 521
 522 /**
 523  * Sets a UI-specific boolean setting for an account.
 524  *
 525  * @param account The account.
 526  * @param ui      The UI name.
 527  * @param name    The name of the setting.
 528  * @param value   The setting's value.
 529  */
 530 void purple_account_set_ui_bool(PurpleAccount *account, const char *ui,
 531                                                           const char *name, gboolean value);
 532
 533 /**
 534  * Returns whether or not the account is connected.
 535  *
 536  * @param account The account.
 537  *
 538  * @return @c TRUE if connected, or @c FALSE otherwise.
 539  */
 540 gboolean purple_account_is_connected(const PurpleAccount *account);
 541
 542 /**
 543  * Returns whether or not the account is connecting.
 544  *
 545  * @param account The account.
 546  *
 547  * @return @c TRUE if connecting, or @c FALSE otherwise.
 548  */
 549 gboolean purple_account_is_connecting(const PurpleAccount *account);
 550
 551 /**
 552  * Returns whether or not the account is disconnected.
 553  *
 554  * @param account The account.
 555  *
 556  * @return @c TRUE if disconnected, or @c FALSE otherwise.
 557  */
 558 gboolean purple_account_is_disconnected(const PurpleAccount *account);
 559
 560 /**
 561  * Returns the account's username.
 562  *
 563  * @param account The account.
 564  *
 565  * @return The username.
 566  */
 567 const char *purple_account_get_username(const PurpleAccount *account);
 568
 569 /**
 570  * Returns the account's password.
 571  *
 572  * @param account The account.
 573  *
 574  * @return The password.
 575  */
 576 const char *purple_account_get_password(const PurpleAccount *account);
 577
 578 /**
 579  * Returns the account's alias.
 580  *
 581  * @param account The account.
 582  *
 583  * @return The alias.
 584  */
 585 const char *purple_account_get_alias(const PurpleAccount *account);
 586
 587 /**
 588  * Returns the account's user information.
 589  *
 590  * @param account The account.
 591  *
 592  * @return The user information.
 593  */
 594 const char *purple_account_get_user_info(const PurpleAccount *account);
 595
 596 /**
 597  * Gets the account's buddy icon path.
 598  *
 599  * @param account The account.
 600  *
 601  * @return The buddy icon's non-cached path.
 602  */
 603 const char *purple_account_get_buddy_icon_path(const PurpleAccount *account);
 604
 605 /**
 606  * Returns the account's protocol ID.
 607  *
 608  * @param account The account.
 609  *
 610  * @return The protocol ID.
 611  */
 612 const char *purple_account_get_protocol_id(const PurpleAccount *account);
 613
 614 /**
 615  * Returns the account's protocol name.
 616  *
 617  * @param account The account.
 618  *
 619  * @return The protocol name.
 620  */
 621 const char *purple_account_get_protocol_name(const PurpleAccount *account);
 622
 623 /**
 624  * Returns the account's connection.
 625  *
 626  * @param account The account.
 627  *
 628  * @return The connection.
 629  */
 630 PurpleConnection *purple_account_get_connection(const PurpleAccount *account);
 631
 632 /**
 633  * Returns whether or not this account should save its password.
 634  *
 635  * @param account The account.
 636  *
 637  * @return @c TRUE if it should remember the password.
 638  */
 639 gboolean purple_account_get_remember_password(const PurpleAccount *account);
 640
 641 /**
 642  * Returns whether or not this account should check for mail.
 643  *
 644  * @param account The account.
 645  *
 646  * @return @c TRUE if it should check for mail.
 647  */
 648 gboolean purple_account_get_check_mail(const PurpleAccount *account);
 649
 650 /**
 651  * Returns whether or not this account is enabled for the
 652  * specified UI.
 653  *
 654  * @param account The account.
 655  * @param ui      The UI.
 656  *
 657  * @return @c TRUE if it enabled on this UI.
 658  */
 659 gboolean purple_account_get_enabled(const PurpleAccount *account,
 660                                   const char *ui);
 661
 662 /**
 663  * Returns the account's proxy information.
 664  *
 665  * @param account The account.
 666  *
 667  * @return The proxy information.
 668  */
 669 PurpleProxyInfo *purple_account_get_proxy_info(const PurpleAccount *account);
 670
 671 /**
 672  * Returns the active status for this account.  This looks through
 673  * the PurplePresence associated with this account and returns the
 674  * PurpleStatus that has its active flag set to "TRUE."  There can be
 675  * only one active PurpleStatus in a PurplePresence.
 676  *
 677  * @param account   The account.
 678  *
 679  * @return The active status.
 680  */
 681 PurpleStatus *purple_account_get_active_status(const PurpleAccount *account);
 682
 683 /**
 684  * Returns the account status with the specified ID.
 685  *
 686  * Note that this works differently than purple_buddy_get_status() in that
 687  * it will only return NULL if the status was not registered.
 688  *
 689  * @param account   The account.
 690  * @param status_id The status ID.
 691  *
 692  * @return The status, or NULL if it was never registered.
 693  */
 694 PurpleStatus *purple_account_get_status(const PurpleAccount *account,
 695                                                                         const char *status_id);
 696
 697 /**
 698  * Returns the account status type with the specified ID.
 699  *
 700  * @param account The account.
 701  * @param id      The ID of the status type to find.
 702  *
 703  * @return The status type if found, or NULL.
 704  */
 705 PurpleStatusType *purple_account_get_status_type(const PurpleAccount *account,
 706                                                                                          const char *id);
 707
 708 /**
 709  * Returns the account status type with the specified primitive.
 710  * Note: It is possible for an account to have more than one
 711  * PurpleStatusType with the same primitive.  In this case, the
 712  * first PurpleStatusType is returned.
 713  *
 714  * @param account   The account.
 715  * @param primitive The type of the status type to find.
 716  *
 717  * @return The status if found, or NULL.
 718  */
 719 PurpleStatusType *purple_account_get_status_type_with_primitive(
 720                                                         const PurpleAccount *account,
 721                                                         PurpleStatusPrimitive primitive);
 722
 723 /**
 724  * Returns the account's presence.
 725  *
 726  * @param account The account.
 727  *
 728  * @return The account's presence.
 729  */
 730 PurplePresence *purple_account_get_presence(const PurpleAccount *account);
 731
 732 /**
 733  * Returns whether or not an account status is active.
 734  *
 735  * @param account   The account.
 736  * @param status_id The status ID.
 737  *
 738  * @return TRUE if active, or FALSE if not.
 739  */
 740 gboolean purple_account_is_status_active(const PurpleAccount *account,
 741                                                                            const char *status_id);
 742
 743 /**
 744  * Returns the account's status types.
 745  *
 746  * @param account The account.
 747  *
 748  * @constreturn The account's status types.
 749  */
 750 GList *purple_account_get_status_types(const PurpleAccount *account);
 751
 752 /**
 753  * Returns a protocol-specific integer setting for an account.
 754  *
 755  * @param account       The account.
 756  * @param name          The name of the setting.
 757  * @param default_value The default value.
 758  *
 759  * @return The value.
 760  */
 761 int purple_account_get_int(const PurpleAccount *account, const char *name,
 762                                                  int default_value);
 763
 764 /**
 765  * Returns a protocol-specific string setting for an account.
 766  *
 767  * @param account       The account.
 768  * @param name          The name of the setting.
 769  * @param default_value The default value.
 770  *
 771  * @return The value.
 772  */
 773 const char *purple_account_get_string(const PurpleAccount *account,
 774                                                                         const char *name,
 775                                                                         const char *default_value);
 776
 777 /**
 778  * Returns a protocol-specific boolean setting for an account.
 779  *
 780  * @param account       The account.
 781  * @param name          The name of the setting.
 782  * @param default_value The default value.
 783  *
 784  * @return The value.
 785  */
 786 gboolean purple_account_get_bool(const PurpleAccount *account, const char *name,
 787                                                            gboolean default_value);
 788
 789 /**
 790  * Returns a UI-specific integer setting for an account.
 791  *
 792  * @param account       The account.
 793  * @param ui            The UI name.
 794  * @param name          The name of the setting.
 795  * @param default_value The default value.
 796  *
 797  * @return The value.
 798  */
 799 int purple_account_get_ui_int(const PurpleAccount *account, const char *ui,
 800                                                         const char *name, int default_value);
 801
 802 /**
 803  * Returns a UI-specific string setting for an account.
 804  *
 805  * @param account       The account.
 806  * @param ui            The UI name.
 807  * @param name          The name of the setting.
 808  * @param default_value The default value.
 809  *
 810  * @return The value.
 811  */
 812 const char *purple_account_get_ui_string(const PurpleAccount *account,
 813                                                                            const char *ui, const char *name,
 814                                                                            const char *default_value);
 815
 816 /**
 817  * Returns a UI-specific boolean setting for an account.
 818  *
 819  * @param account       The account.
 820  * @param ui            The UI name.
 821  * @param name          The name of the setting.
 822  * @param default_value The default value.
 823  *
 824  * @return The value.
 825  */
 826 gboolean purple_account_get_ui_bool(const PurpleAccount *account, const char *ui,
 827                                                                   const char *name, gboolean default_value);
 828
 829
 830 /**
 831  * Returns the system log for an account.
 832  *
 833  * @param account The account.
 834  * @param create  Should it be created if it doesn't exist?
 835  *
 836  * @return The log.
 837  *
 838  * @note Callers should almost always pass @c FALSE for @a create.
 839  *       Passing @c TRUE could result in an existing log being reopened,
 840  *       if the log has already been closed, which not all loggers deal
 841  *       with appropriately.
 842  */
 843 PurpleLog *purple_account_get_log(PurpleAccount *account, gboolean create);
 844
 845 /**
 846  * Frees the system log of an account
 847  *
 848  * @param account The account.
 849  */
 850 void purple_account_destroy_log(PurpleAccount *account);
 851
 852 /**
 853  * Adds a buddy to the server-side buddy list for the specified account.
 854  *
 855  * @param account The account.
 856  * @param buddy The buddy to add.
 857  */
 858 void purple_account_add_buddy(PurpleAccount *account, PurpleBuddy *buddy);
 859 /**
 860  * Adds a list of buddies to the server-side buddy list.
 861  *
 862  * @param account The account.
 863  * @param buddies The list of PurpleBlistNodes representing the buddies to add.
 864  */
 865 void purple_account_add_buddies(PurpleAccount *account, GList *buddies);
 866
 867 /**
 868  * Removes a buddy from the server-side buddy list.
 869  *
 870  * @param account The account.
 871  * @param buddy The buddy to remove.
 872  * @param group The group to remove the buddy from.
 873  */
 874 void purple_account_remove_buddy(PurpleAccount *account, PurpleBuddy *buddy,
 875                                                                 PurpleGroup *group);
 876
 877 /**
 878  * Removes a list of buddies from the server-side buddy list.
 879  *
 880  * @note The lists buddies and groups are parallel lists.  Be sure that node n of
 881  *       groups matches node n of buddies.
 882  *
 883  * @param account The account.
 884  * @param buddies The list of buddies to remove.
 885  * @param groups The list of groups to remove buddies from.  Each node of this
 886  *               list should match the corresponding node of buddies.
 887  */
 888 void purple_account_remove_buddies(PurpleAccount *account, GList *buddies,
 889                                                                         GList *groups);
 890
 891 /**
 892  * Removes a group from the server-side buddy list.
 893  *
 894  * @param account The account.
 895  * @param group The group to remove.
 896  */
 897 void purple_account_remove_group(PurpleAccount *account, PurpleGroup *group);
 898
 899 /**
 900  * Changes the password on the specified account.
 901  *
 902  * @param account The account.
 903  * @param orig_pw The old password.
 904  * @param new_pw The new password.
 905  */
 906 void purple_account_change_password(PurpleAccount *account, const char *orig_pw,
 907                                                                         const char *new_pw);
 908
 909 /**
 910  * Whether the account supports sending offline messages to buddy.
 911  *
 912  * @param account The account
 913  * @param buddy   The buddy
 914  */
 915 gboolean purple_account_supports_offline_message(PurpleAccount *account, PurpleBuddy *buddy);
 916
 917 /**
 918  * Get the error that caused the account to be disconnected, or @c NULL if the
 919  * account is happily connected or disconnected without an error.
 920  *
 921  * @param account The account whose error should be retrieved.
 922  * @constreturn   The type of error and a human-readable description of the
 923  *                current error, or @c NULL if there is no current error.  This
 924  *                pointer is guaranteed to remain valid until the @ref
 925  *                account-error-changed signal is emitted for @a account.
 926  */
 927 const PurpleConnectionErrorInfo *purple_account_get_current_error(PurpleAccount *account);
 928
 929 /**
 930  * Clear an account's current error state, resetting it to @c NULL.
 931  *
 932  * @param account The account whose error state should be cleared.
 933  */
 934 void purple_account_clear_current_error(PurpleAccount *account);
 935
 936 /*@}*/
 937
 938 /**************************************************************************/
 939 /** @name Accounts API                                                    */
 940 /**************************************************************************/
 941 /*@{*/
 942
 943 /**
 944  * Adds an account to the list of accounts.
 945  *
 946  * @param account The account.
 947  */
 948 void purple_accounts_add(PurpleAccount *account);
 949
 950 /**
 951  * Removes an account from the list of accounts.
 952  *
 953  * @param account The account.
 954  */
 955 void purple_accounts_remove(PurpleAccount *account);
 956
 957 /**
 958  * Deletes an account.
 959  *
 960  * This will remove any buddies from the buddy list that belong to this
 961  * account, buddy pounces that belong to this account, and will also
 962  * destroy @a account.
 963  *
 964  * @param account The account.
 965  */
 966 void purple_accounts_delete(PurpleAccount *account);
 967
 968 /**
 969  * Reorders an account.
 970  *
 971  * @param account   The account to reorder.
 972  * @param new_index The new index for the account.
 973  */
 974 void purple_accounts_reorder(PurpleAccount *account, gint new_index);
 975
 976 /**
 977  * Returns a list of all accounts.
 978  *
 979  * @constreturn A list of all accounts.
 980  */
 981 GList *purple_accounts_get_all(void);
 982
 983 /**
 984  * Returns a list of all enabled accounts
 985  *
 986  * @return A list of all enabled accounts. The list is owned
 987  *         by the caller, and must be g_list_free()d to avoid
 988  *         leaking the nodes.
 989  */
 990 GList *purple_accounts_get_all_active(void);
 991
 992 /**
 993  * Finds an account with the specified name and protocol id.
 994  *
 995  * @param name     The account username.
 996  * @param protocol The account protocol ID.
 997  *
 998  * @return The account, if found, or @c FALSE otherwise.
 999  */
1000 PurpleAccount *purple_accounts_find(const char *name, const char *protocol);
1001
1002 /**
1003  * This is called by the core after all subsystems and what
1004  * not have been initialized.  It sets all enabled accounts
1005  * to their startup status by signing them on, setting them
1006  * away, etc.
1007  *
1008  * You probably shouldn't call this unless you really know
1009  * what you're doing.
1010  */
1011 void purple_accounts_restore_current_statuses(void);
1012
1013 /*@}*/
1014
1015
1016 /**************************************************************************/
1017 /** @name UI Registration Functions                                       */
1018 /**************************************************************************/
1019 /*@{*/
1020 /**
1021  * Sets the UI operations structure to be used for accounts.
1022  *
1023  * @param ops The UI operations structure.
1024  */
1025 void purple_accounts_set_ui_ops(PurpleAccountUiOps *ops);
1026
1027 /**
1028  * Returns the UI operations structure used for accounts.
1029  *
1030  * @return The UI operations structure in use.
1031  */
1032 PurpleAccountUiOps *purple_accounts_get_ui_ops(void);
1033
1034 /*@}*/
1035
1036
1037 /**************************************************************************/
1038 /** @name Accounts Subsystem                                              */
1039 /**************************************************************************/
1040 /*@{*/
1041
1042 /**
1043  * Returns the accounts subsystem handle.
1044  *
1045  * @return The accounts subsystem handle.
1046  */
1047 void *purple_accounts_get_handle(void);
1048
1049 /**
1050  * Initializes the accounts subsystem.
1051  */
1052 void purple_accounts_init(void);
1053
1054 /**
1055  * Uninitializes the accounts subsystem.
1056  */
1057 void purple_accounts_uninit(void);
1058
1059 /*@}*/
1060
1061 #ifdef __cplusplus
1062 }
1063 #endif
1064
1065 #endif /* _PURPLE_ACCOUNT_H_ */