libpurple/account.h

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