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