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