1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/account.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,1065 @@
1.4 +/**
1.5 + * @file account.h Account API
1.6 + * @ingroup core
1.7 + * @see @ref account-signals
1.8 + */
1.9 +
1.10 +/* purple
1.11 + *
1.12 + * Purple is the legal property of its developers, whose names are too numerous
1.13 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 + * source distribution.
1.15 + *
1.16 + * This program is free software; you can redistribute it and/or modify
1.17 + * it under the terms of the GNU General Public License as published by
1.18 + * the Free Software Foundation; either version 2 of the License, or
1.19 + * (at your option) any later version.
1.20 + *
1.21 + * This program is distributed in the hope that it will be useful,
1.22 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 + * GNU General Public License for more details.
1.25 + *
1.26 + * You should have received a copy of the GNU General Public License
1.27 + * along with this program; if not, write to the Free Software
1.28 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 + */
1.30 +#ifndef _PURPLE_ACCOUNT_H_
1.31 +#define _PURPLE_ACCOUNT_H_
1.32 +
1.33 +#include <glib.h>
1.34 +#include <glib-object.h>
1.35 +
1.36 +/** @copydoc _PurpleAccountUiOps */
1.37 +typedef struct _PurpleAccountUiOps PurpleAccountUiOps;
1.38 +/** @copydoc _PurpleAccount */
1.39 +typedef struct _PurpleAccount PurpleAccount;
1.40 +
1.41 +typedef gboolean (*PurpleFilterAccountFunc)(PurpleAccount *account);
1.42 +typedef void (*PurpleAccountRequestAuthorizationCb)(void *);
1.43 +typedef void (*PurpleAccountRegistrationCb)(PurpleAccount *account, gboolean succeeded, void *user_data);
1.44 +typedef void (*PurpleAccountUnregistrationCb)(PurpleAccount *account, gboolean succeeded, void *user_data);
1.45 +
1.46 +#include "connection.h"
1.47 +#include "log.h"
1.48 +#include "privacy.h"
1.49 +#include "proxy.h"
1.50 +#include "prpl.h"
1.51 +#include "status.h"
1.52 +
1.53 +/**
1.54 + * Account request types.
1.55 + */
1.56 +typedef enum
1.57 +{
1.58 + PURPLE_ACCOUNT_REQUEST_AUTHORIZATION = 0 /* Account authorization request */
1.59 +} PurpleAccountRequestType;
1.60 +
1.61 +
1.62 +/** Account UI operations, used to notify the user of status changes and when
1.63 + * buddies add this account to their buddy lists.
1.64 + */
1.65 +struct _PurpleAccountUiOps
1.66 +{
1.67 + /** A buddy who is already on this account's buddy list added this account
1.68 + * to their buddy list.
1.69 + */
1.70 + void (*notify_added)(PurpleAccount *account,
1.71 + const char *remote_user,
1.72 + const char *id,
1.73 + const char *alias,
1.74 + const char *message);
1.75 +
1.76 + /** This account's status changed. */
1.77 + void (*status_changed)(PurpleAccount *account,
1.78 + PurpleStatus *status);
1.79 +
1.80 + /** Someone we don't have on our list added us; prompt to add them. */
1.81 + void (*request_add)(PurpleAccount *account,
1.82 + const char *remote_user,
1.83 + const char *id,
1.84 + const char *alias,
1.85 + const char *message);
1.86 +
1.87 + /** Prompt for authorization when someone adds this account to their buddy
1.88 + * list. To authorize them to see this account's presence, call \a
1.89 + * authorize_cb (\a user_data); otherwise call \a deny_cb (\a user_data);
1.90 + * @return a UI-specific handle, as passed to #close_account_request.
1.91 + */
1.92 + void *(*request_authorize)(PurpleAccount *account,
1.93 + const char *remote_user,
1.94 + const char *id,
1.95 + const char *alias,
1.96 + const char *message,
1.97 + gboolean on_list,
1.98 + PurpleAccountRequestAuthorizationCb authorize_cb,
1.99 + PurpleAccountRequestAuthorizationCb deny_cb,
1.100 + void *user_data);
1.101 +
1.102 + /** Close a pending request for authorization. \a ui_handle is a handle
1.103 + * as returned by #request_authorize.
1.104 + */
1.105 + void (*close_account_request)(void *ui_handle);
1.106 +
1.107 + void (*_purple_reserved1)(void);
1.108 + void (*_purple_reserved2)(void);
1.109 + void (*_purple_reserved3)(void);
1.110 + void (*_purple_reserved4)(void);
1.111 +};
1.112 +
1.113 +/** Structure representing an account.
1.114 + */
1.115 +struct _PurpleAccount
1.116 +{
1.117 + char *username; /**< The username. */
1.118 + char *alias; /**< How you appear to yourself. */
1.119 + char *password; /**< The account password. */
1.120 + char *user_info; /**< User information. */
1.121 +
1.122 + char *buddy_icon_path; /**< The buddy icon's non-cached path. */
1.123 +
1.124 + gboolean remember_pass; /**< Remember the password. */
1.125 +
1.126 + char *protocol_id; /**< The ID of the protocol. */
1.127 +
1.128 + PurpleConnection *gc; /**< The connection handle. */
1.129 + gboolean disconnecting; /**< The account is currently disconnecting */
1.130 +
1.131 + GHashTable *settings; /**< Protocol-specific settings. */
1.132 + GHashTable *ui_settings; /**< UI-specific settings. */
1.133 +
1.134 + PurpleProxyInfo *proxy_info; /**< Proxy information. This will be set */
1.135 + /* to NULL when the account inherits */
1.136 + /* proxy settings from global prefs. */
1.137 +
1.138 + /*
1.139 + * TODO: Supplementing the next two linked lists with hash tables
1.140 + * should help performance a lot when these lists are long. This
1.141 + * matters quite a bit for protocols like MSN, where all your
1.142 + * buddies are added to your permit list. Currently we have to
1.143 + * iterate through the entire list if we want to check if someone
1.144 + * is permitted or denied. We should do this for 3.0.0.
1.145 + */
1.146 + GSList *permit; /**< Permit list. */
1.147 + GSList *deny; /**< Deny list. */
1.148 + PurplePrivacyType perm_deny; /**< The permit/deny setting. */
1.149 +
1.150 + GList *status_types; /**< Status types. */
1.151 +
1.152 + PurplePresence *presence; /**< Presence. */
1.153 + PurpleLog *system_log; /**< The system log */
1.154 +
1.155 + void *ui_data; /**< The UI can put data here. */
1.156 + PurpleAccountRegistrationCb registration_cb;
1.157 + void *registration_cb_user_data;
1.158 +
1.159 + gpointer priv; /**< Pointer to opaque private data. */
1.160 +};
1.161 +
1.162 +#ifdef __cplusplus
1.163 +extern "C" {
1.164 +#endif
1.165 +
1.166 +/**************************************************************************/
1.167 +/** @name Account API */
1.168 +/**************************************************************************/
1.169 +/*@{*/
1.170 +
1.171 +/**
1.172 + * Creates a new account.
1.173 + *
1.174 + * @param username The username.
1.175 + * @param protocol_id The protocol ID.
1.176 + *
1.177 + * @return The new account.
1.178 + */
1.179 +PurpleAccount *purple_account_new(const char *username, const char *protocol_id);
1.180 +
1.181 +/**
1.182 + * Destroys an account.
1.183 + *
1.184 + * @param account The account to destroy.
1.185 + */
1.186 +void purple_account_destroy(PurpleAccount *account);
1.187 +
1.188 +/**
1.189 + * Connects to an account.
1.190 + *
1.191 + * @param account The account to connect to.
1.192 + */
1.193 +void purple_account_connect(PurpleAccount *account);
1.194 +
1.195 +/**
1.196 + * Sets the callback for successful registration.
1.197 + *
1.198 + * @param account The account for which this callback should be used
1.199 + * @param cb The callback
1.200 + * @param user_data The user data passed to the callback
1.201 + */
1.202 +void purple_account_set_register_callback(PurpleAccount *account, PurpleAccountRegistrationCb cb, void *user_data);
1.203 +
1.204 +/**
1.205 + * Registers an account.
1.206 + *
1.207 + * @param account The account to register.
1.208 + */
1.209 +void purple_account_register(PurpleAccount *account);
1.210 +
1.211 +/**
1.212 + * Unregisters an account (deleting it from the server).
1.213 + *
1.214 + * @param account The account to unregister.
1.215 + * @param cb Optional callback to be called when unregistration is complete
1.216 + * @param user_data user data to pass to the callback
1.217 + */
1.218 +void purple_account_unregister(PurpleAccount *account, PurpleAccountUnregistrationCb cb, void *user_data);
1.219 +
1.220 +/**
1.221 + * Disconnects from an account.
1.222 + *
1.223 + * @param account The account to disconnect from.
1.224 + */
1.225 +void purple_account_disconnect(PurpleAccount *account);
1.226 +
1.227 +/**
1.228 + * Notifies the user that the account was added to a remote user's
1.229 + * buddy list.
1.230 + *
1.231 + * This will present a dialog informing the user that he was added to the
1.232 + * remote user's buddy list.
1.233 + *
1.234 + * @param account The account that was added.
1.235 + * @param remote_user The name of the user that added this account.
1.236 + * @param id The optional ID of the local account. Rarely used.
1.237 + * @param alias The optional alias of the user.
1.238 + * @param message The optional message sent from the user adding you.
1.239 + */
1.240 +void purple_account_notify_added(PurpleAccount *account, const char *remote_user,
1.241 + const char *id, const char *alias,
1.242 + const char *message);
1.243 +
1.244 +/**
1.245 + * Notifies the user that the account was addded to a remote user's buddy
1.246 + * list and asks ther user if they want to add the remote user to their buddy
1.247 + * list.
1.248 + *
1.249 + * This will present a dialog informing the local user that the remote user
1.250 + * added them to the remote user's buddy list and will ask if they want to add
1.251 + * the remote user to the buddy list.
1.252 + *
1.253 + * @param account The account that was added.
1.254 + * @param remote_user The name of the user that added this account.
1.255 + * @param id The optional ID of the local account. Rarely used.
1.256 + * @param alias The optional alias of the user.
1.257 + * @param message The optional message sent from the user adding you.
1.258 + */
1.259 +void purple_account_request_add(PurpleAccount *account, const char *remote_user,
1.260 + const char *id, const char *alias,
1.261 + const char *message);
1.262 +
1.263 +/**
1.264 + * Notifies the user that a remote user has wants to add the local user
1.265 + * to his or her buddy list and requires authorization to do so.
1.266 + *
1.267 + * This will present a dialog informing the user of this and ask if the
1.268 + * user authorizes or denies the remote user from adding him.
1.269 + *
1.270 + * @param account The account that was added
1.271 + * @param remote_user The name of the user that added this account.
1.272 + * @param id The optional ID of the local account. Rarely used.
1.273 + * @param alias The optional alias of the remote user.
1.274 + * @param message The optional message sent by the user wanting to add you.
1.275 + * @param on_list Is the remote user already on the buddy list?
1.276 + * @param auth_cb The callback called when the local user accepts
1.277 + * @param deny_cb The callback called when the local user rejects
1.278 + * @param user_data Data to be passed back to the above callbacks
1.279 + *
1.280 + * @return A UI-specific handle.
1.281 + */
1.282 +void *purple_account_request_authorization(PurpleAccount *account, const char *remote_user,
1.283 + const char *id, const char *alias, const char *message, gboolean on_list,
1.284 + PurpleAccountRequestAuthorizationCb auth_cb, PurpleAccountRequestAuthorizationCb deny_cb, void *user_data);
1.285 +
1.286 +/**
1.287 + * Close account requests registered for the given PurpleAccount
1.288 + *
1.289 + * @param account The account for which requests should be closed
1.290 + */
1.291 +void purple_account_request_close_with_account(PurpleAccount *account);
1.292 +
1.293 +/**
1.294 + * Close the account request for the given ui handle
1.295 + *
1.296 + * @param ui_handle The ui specific handle for which requests should be closed
1.297 + */
1.298 +void purple_account_request_close(void *ui_handle);
1.299 +
1.300 +/**
1.301 + * Requests a password from the user for the account. Does not set the
1.302 + * account password on success; do that in ok_cb if desired.
1.303 + *
1.304 + * @param account The account to request the password for.
1.305 + * @param ok_cb The callback for the OK button.
1.306 + * @param cancel_cb The callback for the cancel button.
1.307 + * @param user_data User data to be passed into callbacks.
1.308 + */
1.309 +void purple_account_request_password(PurpleAccount *account, GCallback ok_cb,
1.310 + GCallback cancel_cb, void *user_data);
1.311 +
1.312 +/**
1.313 + * Requests information from the user to change the account's password.
1.314 + *
1.315 + * @param account The account to change the password on.
1.316 + */
1.317 +void purple_account_request_change_password(PurpleAccount *account);
1.318 +
1.319 +/**
1.320 + * Requests information from the user to change the account's
1.321 + * user information.
1.322 + *
1.323 + * @param account The account to change the user information on.
1.324 + */
1.325 +void purple_account_request_change_user_info(PurpleAccount *account);
1.326 +
1.327 +/**
1.328 + * Sets the account's username.
1.329 + *
1.330 + * @param account The account.
1.331 + * @param username The username.
1.332 + */
1.333 +void purple_account_set_username(PurpleAccount *account, const char *username);
1.334 +
1.335 +/**
1.336 + * Sets the account's password.
1.337 + *
1.338 + * @param account The account.
1.339 + * @param password The password.
1.340 + */
1.341 +void purple_account_set_password(PurpleAccount *account, const char *password);
1.342 +
1.343 +/**
1.344 + * Sets the account's alias.
1.345 + *
1.346 + * @param account The account.
1.347 + * @param alias The alias.
1.348 + */
1.349 +void purple_account_set_alias(PurpleAccount *account, const char *alias);
1.350 +
1.351 +/**
1.352 + * Sets the account's user information
1.353 + *
1.354 + * @param account The account.
1.355 + * @param user_info The user information.
1.356 + */
1.357 +void purple_account_set_user_info(PurpleAccount *account, const char *user_info);
1.358 +
1.359 +/**
1.360 + * Sets the account's buddy icon path.
1.361 + *
1.362 + * @param account The account.
1.363 + * @param path The buddy icon non-cached path.
1.364 + */
1.365 +void purple_account_set_buddy_icon_path(PurpleAccount *account, const char *path);
1.366 +
1.367 +/**
1.368 + * Sets the account's protocol ID.
1.369 + *
1.370 + * @param account The account.
1.371 + * @param protocol_id The protocol ID.
1.372 + */
1.373 +void purple_account_set_protocol_id(PurpleAccount *account,
1.374 + const char *protocol_id);
1.375 +
1.376 +/**
1.377 + * Sets the account's connection.
1.378 + *
1.379 + * @param account The account.
1.380 + * @param gc The connection.
1.381 + */
1.382 +void purple_account_set_connection(PurpleAccount *account, PurpleConnection *gc);
1.383 +
1.384 +/**
1.385 + * Sets whether or not this account should save its password.
1.386 + *
1.387 + * @param account The account.
1.388 + * @param value @c TRUE if it should remember the password.
1.389 + */
1.390 +void purple_account_set_remember_password(PurpleAccount *account, gboolean value);
1.391 +
1.392 +/**
1.393 + * Sets whether or not this account should check for mail.
1.394 + *
1.395 + * @param account The account.
1.396 + * @param value @c TRUE if it should check for mail.
1.397 + */
1.398 +void purple_account_set_check_mail(PurpleAccount *account, gboolean value);
1.399 +
1.400 +/**
1.401 + * Sets whether or not this account is enabled for the specified
1.402 + * UI.
1.403 + *
1.404 + * @param account The account.
1.405 + * @param ui The UI.
1.406 + * @param value @c TRUE if it is enabled.
1.407 + */
1.408 +void purple_account_set_enabled(PurpleAccount *account, const char *ui,
1.409 + gboolean value);
1.410 +
1.411 +/**
1.412 + * Sets the account's proxy information.
1.413 + *
1.414 + * @param account The account.
1.415 + * @param info The proxy information.
1.416 + */
1.417 +void purple_account_set_proxy_info(PurpleAccount *account, PurpleProxyInfo *info);
1.418 +
1.419 +/**
1.420 + * Sets the account's status types.
1.421 + *
1.422 + * @param account The account.
1.423 + * @param status_types The list of status types.
1.424 + */
1.425 +void purple_account_set_status_types(PurpleAccount *account, GList *status_types);
1.426 +
1.427 +/**
1.428 + * Variadic version of purple_account_set_status_list(); the variadic list
1.429 + * replaces @a attrs, and should be <tt>NULL</tt>-terminated.
1.430 + *
1.431 + * @copydoc purple_account_set_status_list()
1.432 + */
1.433 +void purple_account_set_status(PurpleAccount *account, const char *status_id,
1.434 + gboolean active, ...) G_GNUC_NULL_TERMINATED;
1.435 +
1.436 +
1.437 +/**
1.438 + * Activates or deactivates a status. All changes to the statuses of
1.439 + * an account go through this function or purple_account_set_status().
1.440 + *
1.441 + * You can only deactivate an exclusive status by activating another exclusive
1.442 + * status. So, if @a status_id is an exclusive status and @a active is @c
1.443 + * FALSE, this function does nothing.
1.444 + *
1.445 + * @param account The account.
1.446 + * @param status_id The ID of the status.
1.447 + * @param active Whether @a status_id is to be activated (<tt>TRUE</tt>) or
1.448 + * deactivated (<tt>FALSE</tt>).
1.449 + * @param attrs A list of <tt>const char *</tt> attribute names followed by
1.450 + * <tt>const char *</tt> attribute values for the status.
1.451 + * (For example, one pair might be <tt>"message"</tt> followed
1.452 + * by <tt>"hello, talk to me!"</tt>.)
1.453 + */
1.454 +void purple_account_set_status_list(PurpleAccount *account,
1.455 + const char *status_id, gboolean active, GList *attrs);
1.456 +
1.457 +/**
1.458 + * Clears all protocol-specific settings on an account.
1.459 + *
1.460 + * @param account The account.
1.461 + */
1.462 +void purple_account_clear_settings(PurpleAccount *account);
1.463 +
1.464 +/**
1.465 + * Removes an account-specific setting by name.
1.466 + *
1.467 + * @param account The account.
1.468 + * @param setting The setting to remove.
1.469 + *
1.470 + * @since 2.6.0
1.471 + */
1.472 +void purple_account_remove_setting(PurpleAccount *account, const char *setting);
1.473 +
1.474 +/**
1.475 + * Sets a protocol-specific integer setting for an account.
1.476 + *
1.477 + * @param account The account.
1.478 + * @param name The name of the setting.
1.479 + * @param value The setting's value.
1.480 + */
1.481 +void purple_account_set_int(PurpleAccount *account, const char *name, int value);
1.482 +
1.483 +/**
1.484 + * Sets a protocol-specific string setting for an account.
1.485 + *
1.486 + * @param account The account.
1.487 + * @param name The name of the setting.
1.488 + * @param value The setting's value.
1.489 + */
1.490 +void purple_account_set_string(PurpleAccount *account, const char *name,
1.491 + const char *value);
1.492 +
1.493 +/**
1.494 + * Sets a protocol-specific boolean setting for an account.
1.495 + *
1.496 + * @param account The account.
1.497 + * @param name The name of the setting.
1.498 + * @param value The setting's value.
1.499 + */
1.500 +void purple_account_set_bool(PurpleAccount *account, const char *name,
1.501 + gboolean value);
1.502 +
1.503 +/**
1.504 + * Sets a UI-specific integer setting for an account.
1.505 + *
1.506 + * @param account The account.
1.507 + * @param ui The UI name.
1.508 + * @param name The name of the setting.
1.509 + * @param value The setting's value.
1.510 + */
1.511 +void purple_account_set_ui_int(PurpleAccount *account, const char *ui,
1.512 + const char *name, int value);
1.513 +
1.514 +/**
1.515 + * Sets a UI-specific string setting for an account.
1.516 + *
1.517 + * @param account The account.
1.518 + * @param ui The UI name.
1.519 + * @param name The name of the setting.
1.520 + * @param value The setting's value.
1.521 + */
1.522 +void purple_account_set_ui_string(PurpleAccount *account, const char *ui,
1.523 + const char *name, const char *value);
1.524 +
1.525 +/**
1.526 + * Sets a UI-specific boolean setting for an account.
1.527 + *
1.528 + * @param account The account.
1.529 + * @param ui The UI name.
1.530 + * @param name The name of the setting.
1.531 + * @param value The setting's value.
1.532 + */
1.533 +void purple_account_set_ui_bool(PurpleAccount *account, const char *ui,
1.534 + const char *name, gboolean value);
1.535 +
1.536 +/**
1.537 + * Returns whether or not the account is connected.
1.538 + *
1.539 + * @param account The account.
1.540 + *
1.541 + * @return @c TRUE if connected, or @c FALSE otherwise.
1.542 + */
1.543 +gboolean purple_account_is_connected(const PurpleAccount *account);
1.544 +
1.545 +/**
1.546 + * Returns whether or not the account is connecting.
1.547 + *
1.548 + * @param account The account.
1.549 + *
1.550 + * @return @c TRUE if connecting, or @c FALSE otherwise.
1.551 + */
1.552 +gboolean purple_account_is_connecting(const PurpleAccount *account);
1.553 +
1.554 +/**
1.555 + * Returns whether or not the account is disconnected.
1.556 + *
1.557 + * @param account The account.
1.558 + *
1.559 + * @return @c TRUE if disconnected, or @c FALSE otherwise.
1.560 + */
1.561 +gboolean purple_account_is_disconnected(const PurpleAccount *account);
1.562 +
1.563 +/**
1.564 + * Returns the account's username.
1.565 + *
1.566 + * @param account The account.
1.567 + *
1.568 + * @return The username.
1.569 + */
1.570 +const char *purple_account_get_username(const PurpleAccount *account);
1.571 +
1.572 +/**
1.573 + * Returns the account's password.
1.574 + *
1.575 + * @param account The account.
1.576 + *
1.577 + * @return The password.
1.578 + */
1.579 +const char *purple_account_get_password(const PurpleAccount *account);
1.580 +
1.581 +/**
1.582 + * Returns the account's alias.
1.583 + *
1.584 + * @param account The account.
1.585 + *
1.586 + * @return The alias.
1.587 + */
1.588 +const char *purple_account_get_alias(const PurpleAccount *account);
1.589 +
1.590 +/**
1.591 + * Returns the account's user information.
1.592 + *
1.593 + * @param account The account.
1.594 + *
1.595 + * @return The user information.
1.596 + */
1.597 +const char *purple_account_get_user_info(const PurpleAccount *account);
1.598 +
1.599 +/**
1.600 + * Gets the account's buddy icon path.
1.601 + *
1.602 + * @param account The account.
1.603 + *
1.604 + * @return The buddy icon's non-cached path.
1.605 + */
1.606 +const char *purple_account_get_buddy_icon_path(const PurpleAccount *account);
1.607 +
1.608 +/**
1.609 + * Returns the account's protocol ID.
1.610 + *
1.611 + * @param account The account.
1.612 + *
1.613 + * @return The protocol ID.
1.614 + */
1.615 +const char *purple_account_get_protocol_id(const PurpleAccount *account);
1.616 +
1.617 +/**
1.618 + * Returns the account's protocol name.
1.619 + *
1.620 + * @param account The account.
1.621 + *
1.622 + * @return The protocol name.
1.623 + */
1.624 +const char *purple_account_get_protocol_name(const PurpleAccount *account);
1.625 +
1.626 +/**
1.627 + * Returns the account's connection.
1.628 + *
1.629 + * @param account The account.
1.630 + *
1.631 + * @return The connection.
1.632 + */
1.633 +PurpleConnection *purple_account_get_connection(const PurpleAccount *account);
1.634 +
1.635 +/**
1.636 + * Returns whether or not this account should save its password.
1.637 + *
1.638 + * @param account The account.
1.639 + *
1.640 + * @return @c TRUE if it should remember the password.
1.641 + */
1.642 +gboolean purple_account_get_remember_password(const PurpleAccount *account);
1.643 +
1.644 +/**
1.645 + * Returns whether or not this account should check for mail.
1.646 + *
1.647 + * @param account The account.
1.648 + *
1.649 + * @return @c TRUE if it should check for mail.
1.650 + */
1.651 +gboolean purple_account_get_check_mail(const PurpleAccount *account);
1.652 +
1.653 +/**
1.654 + * Returns whether or not this account is enabled for the
1.655 + * specified UI.
1.656 + *
1.657 + * @param account The account.
1.658 + * @param ui The UI.
1.659 + *
1.660 + * @return @c TRUE if it enabled on this UI.
1.661 + */
1.662 +gboolean purple_account_get_enabled(const PurpleAccount *account,
1.663 + const char *ui);
1.664 +
1.665 +/**
1.666 + * Returns the account's proxy information.
1.667 + *
1.668 + * @param account The account.
1.669 + *
1.670 + * @return The proxy information.
1.671 + */
1.672 +PurpleProxyInfo *purple_account_get_proxy_info(const PurpleAccount *account);
1.673 +
1.674 +/**
1.675 + * Returns the active status for this account. This looks through
1.676 + * the PurplePresence associated with this account and returns the
1.677 + * PurpleStatus that has its active flag set to "TRUE." There can be
1.678 + * only one active PurpleStatus in a PurplePresence.
1.679 + *
1.680 + * @param account The account.
1.681 + *
1.682 + * @return The active status.
1.683 + */
1.684 +PurpleStatus *purple_account_get_active_status(const PurpleAccount *account);
1.685 +
1.686 +/**
1.687 + * Returns the account status with the specified ID.
1.688 + *
1.689 + * Note that this works differently than purple_buddy_get_status() in that
1.690 + * it will only return NULL if the status was not registered.
1.691 + *
1.692 + * @param account The account.
1.693 + * @param status_id The status ID.
1.694 + *
1.695 + * @return The status, or NULL if it was never registered.
1.696 + */
1.697 +PurpleStatus *purple_account_get_status(const PurpleAccount *account,
1.698 + const char *status_id);
1.699 +
1.700 +/**
1.701 + * Returns the account status type with the specified ID.
1.702 + *
1.703 + * @param account The account.
1.704 + * @param id The ID of the status type to find.
1.705 + *
1.706 + * @return The status type if found, or NULL.
1.707 + */
1.708 +PurpleStatusType *purple_account_get_status_type(const PurpleAccount *account,
1.709 + const char *id);
1.710 +
1.711 +/**
1.712 + * Returns the account status type with the specified primitive.
1.713 + * Note: It is possible for an account to have more than one
1.714 + * PurpleStatusType with the same primitive. In this case, the
1.715 + * first PurpleStatusType is returned.
1.716 + *
1.717 + * @param account The account.
1.718 + * @param primitive The type of the status type to find.
1.719 + *
1.720 + * @return The status if found, or NULL.
1.721 + */
1.722 +PurpleStatusType *purple_account_get_status_type_with_primitive(
1.723 + const PurpleAccount *account,
1.724 + PurpleStatusPrimitive primitive);
1.725 +
1.726 +/**
1.727 + * Returns the account's presence.
1.728 + *
1.729 + * @param account The account.
1.730 + *
1.731 + * @return The account's presence.
1.732 + */
1.733 +PurplePresence *purple_account_get_presence(const PurpleAccount *account);
1.734 +
1.735 +/**
1.736 + * Returns whether or not an account status is active.
1.737 + *
1.738 + * @param account The account.
1.739 + * @param status_id The status ID.
1.740 + *
1.741 + * @return TRUE if active, or FALSE if not.
1.742 + */
1.743 +gboolean purple_account_is_status_active(const PurpleAccount *account,
1.744 + const char *status_id);
1.745 +
1.746 +/**
1.747 + * Returns the account's status types.
1.748 + *
1.749 + * @param account The account.
1.750 + *
1.751 + * @constreturn The account's status types.
1.752 + */
1.753 +GList *purple_account_get_status_types(const PurpleAccount *account);
1.754 +
1.755 +/**
1.756 + * Returns a protocol-specific integer setting for an account.
1.757 + *
1.758 + * @param account The account.
1.759 + * @param name The name of the setting.
1.760 + * @param default_value The default value.
1.761 + *
1.762 + * @return The value.
1.763 + */
1.764 +int purple_account_get_int(const PurpleAccount *account, const char *name,
1.765 + int default_value);
1.766 +
1.767 +/**
1.768 + * Returns a protocol-specific string setting for an account.
1.769 + *
1.770 + * @param account The account.
1.771 + * @param name The name of the setting.
1.772 + * @param default_value The default value.
1.773 + *
1.774 + * @return The value.
1.775 + */
1.776 +const char *purple_account_get_string(const PurpleAccount *account,
1.777 + const char *name,
1.778 + const char *default_value);
1.779 +
1.780 +/**
1.781 + * Returns a protocol-specific boolean setting for an account.
1.782 + *
1.783 + * @param account The account.
1.784 + * @param name The name of the setting.
1.785 + * @param default_value The default value.
1.786 + *
1.787 + * @return The value.
1.788 + */
1.789 +gboolean purple_account_get_bool(const PurpleAccount *account, const char *name,
1.790 + gboolean default_value);
1.791 +
1.792 +/**
1.793 + * Returns a UI-specific integer setting for an account.
1.794 + *
1.795 + * @param account The account.
1.796 + * @param ui The UI name.
1.797 + * @param name The name of the setting.
1.798 + * @param default_value The default value.
1.799 + *
1.800 + * @return The value.
1.801 + */
1.802 +int purple_account_get_ui_int(const PurpleAccount *account, const char *ui,
1.803 + const char *name, int default_value);
1.804 +
1.805 +/**
1.806 + * Returns a UI-specific string setting for an account.
1.807 + *
1.808 + * @param account The account.
1.809 + * @param ui The UI name.
1.810 + * @param name The name of the setting.
1.811 + * @param default_value The default value.
1.812 + *
1.813 + * @return The value.
1.814 + */
1.815 +const char *purple_account_get_ui_string(const PurpleAccount *account,
1.816 + const char *ui, const char *name,
1.817 + const char *default_value);
1.818 +
1.819 +/**
1.820 + * Returns a UI-specific boolean setting for an account.
1.821 + *
1.822 + * @param account The account.
1.823 + * @param ui The UI name.
1.824 + * @param name The name of the setting.
1.825 + * @param default_value The default value.
1.826 + *
1.827 + * @return The value.
1.828 + */
1.829 +gboolean purple_account_get_ui_bool(const PurpleAccount *account, const char *ui,
1.830 + const char *name, gboolean default_value);
1.831 +
1.832 +
1.833 +/**
1.834 + * Returns the system log for an account.
1.835 + *
1.836 + * @param account The account.
1.837 + * @param create Should it be created if it doesn't exist?
1.838 + *
1.839 + * @return The log.
1.840 + *
1.841 + * @note Callers should almost always pass @c FALSE for @a create.
1.842 + * Passing @c TRUE could result in an existing log being reopened,
1.843 + * if the log has already been closed, which not all loggers deal
1.844 + * with appropriately.
1.845 + */
1.846 +PurpleLog *purple_account_get_log(PurpleAccount *account, gboolean create);
1.847 +
1.848 +/**
1.849 + * Frees the system log of an account
1.850 + *
1.851 + * @param account The account.
1.852 + */
1.853 +void purple_account_destroy_log(PurpleAccount *account);
1.854 +
1.855 +/**
1.856 + * Adds a buddy to the server-side buddy list for the specified account.
1.857 + *
1.858 + * @param account The account.
1.859 + * @param buddy The buddy to add.
1.860 + */
1.861 +void purple_account_add_buddy(PurpleAccount *account, PurpleBuddy *buddy);
1.862 +/**
1.863 + * Adds a list of buddies to the server-side buddy list.
1.864 + *
1.865 + * @param account The account.
1.866 + * @param buddies The list of PurpleBlistNodes representing the buddies to add.
1.867 + */
1.868 +void purple_account_add_buddies(PurpleAccount *account, GList *buddies);
1.869 +
1.870 +/**
1.871 + * Removes a buddy from the server-side buddy list.
1.872 + *
1.873 + * @param account The account.
1.874 + * @param buddy The buddy to remove.
1.875 + * @param group The group to remove the buddy from.
1.876 + */
1.877 +void purple_account_remove_buddy(PurpleAccount *account, PurpleBuddy *buddy,
1.878 + PurpleGroup *group);
1.879 +
1.880 +/**
1.881 + * Removes a list of buddies from the server-side buddy list.
1.882 + *
1.883 + * @note The lists buddies and groups are parallel lists. Be sure that node n of
1.884 + * groups matches node n of buddies.
1.885 + *
1.886 + * @param account The account.
1.887 + * @param buddies The list of buddies to remove.
1.888 + * @param groups The list of groups to remove buddies from. Each node of this
1.889 + * list should match the corresponding node of buddies.
1.890 + */
1.891 +void purple_account_remove_buddies(PurpleAccount *account, GList *buddies,
1.892 + GList *groups);
1.893 +
1.894 +/**
1.895 + * Removes a group from the server-side buddy list.
1.896 + *
1.897 + * @param account The account.
1.898 + * @param group The group to remove.
1.899 + */
1.900 +void purple_account_remove_group(PurpleAccount *account, PurpleGroup *group);
1.901 +
1.902 +/**
1.903 + * Changes the password on the specified account.
1.904 + *
1.905 + * @param account The account.
1.906 + * @param orig_pw The old password.
1.907 + * @param new_pw The new password.
1.908 + */
1.909 +void purple_account_change_password(PurpleAccount *account, const char *orig_pw,
1.910 + const char *new_pw);
1.911 +
1.912 +/**
1.913 + * Whether the account supports sending offline messages to buddy.
1.914 + *
1.915 + * @param account The account
1.916 + * @param buddy The buddy
1.917 + */
1.918 +gboolean purple_account_supports_offline_message(PurpleAccount *account, PurpleBuddy *buddy);
1.919 +
1.920 +/**
1.921 + * Get the error that caused the account to be disconnected, or @c NULL if the
1.922 + * account is happily connected or disconnected without an error.
1.923 + *
1.924 + * @param account The account whose error should be retrieved.
1.925 + * @constreturn The type of error and a human-readable description of the
1.926 + * current error, or @c NULL if there is no current error. This
1.927 + * pointer is guaranteed to remain valid until the @ref
1.928 + * account-error-changed signal is emitted for @a account.
1.929 + */
1.930 +const PurpleConnectionErrorInfo *purple_account_get_current_error(PurpleAccount *account);
1.931 +
1.932 +/**
1.933 + * Clear an account's current error state, resetting it to @c NULL.
1.934 + *
1.935 + * @param account The account whose error state should be cleared.
1.936 + */
1.937 +void purple_account_clear_current_error(PurpleAccount *account);
1.938 +
1.939 +/*@}*/
1.940 +
1.941 +/**************************************************************************/
1.942 +/** @name Accounts API */
1.943 +/**************************************************************************/
1.944 +/*@{*/
1.945 +
1.946 +/**
1.947 + * Adds an account to the list of accounts.
1.948 + *
1.949 + * @param account The account.
1.950 + */
1.951 +void purple_accounts_add(PurpleAccount *account);
1.952 +
1.953 +/**
1.954 + * Removes an account from the list of accounts.
1.955 + *
1.956 + * @param account The account.
1.957 + */
1.958 +void purple_accounts_remove(PurpleAccount *account);
1.959 +
1.960 +/**
1.961 + * Deletes an account.
1.962 + *
1.963 + * This will remove any buddies from the buddy list that belong to this
1.964 + * account, buddy pounces that belong to this account, and will also
1.965 + * destroy @a account.
1.966 + *
1.967 + * @param account The account.
1.968 + */
1.969 +void purple_accounts_delete(PurpleAccount *account);
1.970 +
1.971 +/**
1.972 + * Reorders an account.
1.973 + *
1.974 + * @param account The account to reorder.
1.975 + * @param new_index The new index for the account.
1.976 + */
1.977 +void purple_accounts_reorder(PurpleAccount *account, gint new_index);
1.978 +
1.979 +/**
1.980 + * Returns a list of all accounts.
1.981 + *
1.982 + * @constreturn A list of all accounts.
1.983 + */
1.984 +GList *purple_accounts_get_all(void);
1.985 +
1.986 +/**
1.987 + * Returns a list of all enabled accounts
1.988 + *
1.989 + * @return A list of all enabled accounts. The list is owned
1.990 + * by the caller, and must be g_list_free()d to avoid
1.991 + * leaking the nodes.
1.992 + */
1.993 +GList *purple_accounts_get_all_active(void);
1.994 +
1.995 +/**
1.996 + * Finds an account with the specified name and protocol id.
1.997 + *
1.998 + * @param name The account username.
1.999 + * @param protocol The account protocol ID.
1.1000 + *
1.1001 + * @return The account, if found, or @c FALSE otherwise.
1.1002 + */
1.1003 +PurpleAccount *purple_accounts_find(const char *name, const char *protocol);
1.1004 +
1.1005 +/**
1.1006 + * This is called by the core after all subsystems and what
1.1007 + * not have been initialized. It sets all enabled accounts
1.1008 + * to their startup status by signing them on, setting them
1.1009 + * away, etc.
1.1010 + *
1.1011 + * You probably shouldn't call this unless you really know
1.1012 + * what you're doing.
1.1013 + */
1.1014 +void purple_accounts_restore_current_statuses(void);
1.1015 +
1.1016 +/*@}*/
1.1017 +
1.1018 +
1.1019 +/**************************************************************************/
1.1020 +/** @name UI Registration Functions */
1.1021 +/**************************************************************************/
1.1022 +/*@{*/
1.1023 +/**
1.1024 + * Sets the UI operations structure to be used for accounts.
1.1025 + *
1.1026 + * @param ops The UI operations structure.
1.1027 + */
1.1028 +void purple_accounts_set_ui_ops(PurpleAccountUiOps *ops);
1.1029 +
1.1030 +/**
1.1031 + * Returns the UI operations structure used for accounts.
1.1032 + *
1.1033 + * @return The UI operations structure in use.
1.1034 + */
1.1035 +PurpleAccountUiOps *purple_accounts_get_ui_ops(void);
1.1036 +
1.1037 +/*@}*/
1.1038 +
1.1039 +
1.1040 +/**************************************************************************/
1.1041 +/** @name Accounts Subsystem */
1.1042 +/**************************************************************************/
1.1043 +/*@{*/
1.1044 +
1.1045 +/**
1.1046 + * Returns the accounts subsystem handle.
1.1047 + *
1.1048 + * @return The accounts subsystem handle.
1.1049 + */
1.1050 +void *purple_accounts_get_handle(void);
1.1051 +
1.1052 +/**
1.1053 + * Initializes the accounts subsystem.
1.1054 + */
1.1055 +void purple_accounts_init(void);
1.1056 +
1.1057 +/**
1.1058 + * Uninitializes the accounts subsystem.
1.1059 + */
1.1060 +void purple_accounts_uninit(void);
1.1061 +
1.1062 +/*@}*/
1.1063 +
1.1064 +#ifdef __cplusplus
1.1065 +}
1.1066 +#endif
1.1067 +
1.1068 +#endif /* _PURPLE_ACCOUNT_H_ */