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