1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/accountopt.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,395 @@
1.4 +/**
1.5 + * @file accountopt.h Account Options API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +#ifndef _PURPLE_ACCOUNTOPT_H_
1.30 +#define _PURPLE_ACCOUNTOPT_H_
1.31 +
1.32 +#include "prefs.h"
1.33 +
1.34 +/**
1.35 + * An option for an account.
1.36 + *
1.37 + * This is set by protocol plugins, and appears in the account settings
1.38 + * dialogs.
1.39 + */
1.40 +typedef struct
1.41 +{
1.42 + PurplePrefType type; /**< The type of value. */
1.43 +
1.44 + char *text; /**< The text that will appear to the user. */
1.45 + char *pref_name; /**< The name of the associated preference. */
1.46 +
1.47 + union
1.48 + {
1.49 + gboolean boolean; /**< The default boolean value. */
1.50 + int integer; /**< The default integer value. */
1.51 + char *string; /**< The default string value. */
1.52 + GList *list; /**< The default list value. */
1.53 +
1.54 + } default_value;
1.55 +
1.56 + gboolean masked; /**< Whether the value entered should be
1.57 + * obscured from view (for passwords and
1.58 + * similar options)
1.59 + */
1.60 +} PurpleAccountOption;
1.61 +
1.62 +/**
1.63 + * A username split.
1.64 + *
1.65 + * This is used by some protocols to separate the fields of the username
1.66 + * into more human-readable components.
1.67 + */
1.68 +typedef struct
1.69 +{
1.70 + char *text; /**< The text that will appear to the user. */
1.71 + char *default_value; /**< The default value. */
1.72 + char field_sep; /**< The field separator. */
1.73 + gboolean reverse; /**< TRUE if the separator should be found
1.74 + starting a the end of the string, FALSE
1.75 + otherwise */
1.76 +
1.77 +} PurpleAccountUserSplit;
1.78 +
1.79 +#ifdef __cplusplus
1.80 +extern "C" {
1.81 +#endif
1.82 +
1.83 +/**************************************************************************/
1.84 +/** @name Account Option API */
1.85 +/**************************************************************************/
1.86 +/*@{*/
1.87 +
1.88 +/**
1.89 + * Creates a new account option. If you know what @a type will be in advance,
1.90 + * consider using purple_account_option_bool_new(),
1.91 + * purple_account_option_int_new(), purple_account_option_string_new() or
1.92 + * purple_account_option_list_new() (as appropriate) instead.
1.93 + *
1.94 + * @param type The type of option.
1.95 + * @param text The text of the option.
1.96 + * @param pref_name The account preference name for the option.
1.97 + *
1.98 + * @return The account option.
1.99 + */
1.100 +PurpleAccountOption *purple_account_option_new(PurplePrefType type,
1.101 + const char *text, const char *pref_name);
1.102 +
1.103 +/**
1.104 + * Creates a new boolean account option.
1.105 + *
1.106 + * @param text The text of the option.
1.107 + * @param pref_name The account preference name for the option.
1.108 + * @param default_value The default value.
1.109 + *
1.110 + * @return The account option.
1.111 + */
1.112 +PurpleAccountOption *purple_account_option_bool_new(const char *text,
1.113 + const char *pref_name, gboolean default_value);
1.114 +
1.115 +/**
1.116 + * Creates a new integer account option.
1.117 + *
1.118 + * @param text The text of the option.
1.119 + * @param pref_name The account preference name for the option.
1.120 + * @param default_value The default value.
1.121 + *
1.122 + * @return The account option.
1.123 + */
1.124 +PurpleAccountOption *purple_account_option_int_new(const char *text,
1.125 + const char *pref_name, int default_value);
1.126 +
1.127 +/**
1.128 + * Creates a new string account option.
1.129 + *
1.130 + * @param text The text of the option.
1.131 + * @param pref_name The account preference name for the option.
1.132 + * @param default_value The default value.
1.133 + *
1.134 + * @return The account option.
1.135 + */
1.136 +PurpleAccountOption *purple_account_option_string_new(const char *text,
1.137 + const char *pref_name, const char *default_value);
1.138 +
1.139 +/**
1.140 + * Creates a new list account option.
1.141 + *
1.142 + * The list passed will be owned by the account option, and the
1.143 + * strings inside will be freed automatically.
1.144 + *
1.145 + * The list is a list of #PurpleKeyValuePair items. The key is the label that
1.146 + * should be displayed to the user, and the <tt>(const char *)</tt> value is
1.147 + * the internal ID that should be passed to purple_account_set_string() to
1.148 + * choose that value.
1.149 + *
1.150 + * @param text The text of the option.
1.151 + * @param pref_name The account preference name for the option.
1.152 + * @param list The key, value list.
1.153 + *
1.154 + * @return The account option.
1.155 + */
1.156 +PurpleAccountOption *purple_account_option_list_new(const char *text,
1.157 + const char *pref_name, GList *list);
1.158 +
1.159 +/**
1.160 + * Destroys an account option.
1.161 + *
1.162 + * @param option The option to destroy.
1.163 + */
1.164 +void purple_account_option_destroy(PurpleAccountOption *option);
1.165 +
1.166 +/**
1.167 + * Sets the default boolean value for an account option.
1.168 + *
1.169 + * @param option The account option.
1.170 + * @param value The default boolean value.
1.171 + */
1.172 +void purple_account_option_set_default_bool(PurpleAccountOption *option,
1.173 + gboolean value);
1.174 +
1.175 +/**
1.176 + * Sets the default integer value for an account option.
1.177 + *
1.178 + * @param option The account option.
1.179 + * @param value The default integer value.
1.180 + */
1.181 +void purple_account_option_set_default_int(PurpleAccountOption *option,
1.182 + int value);
1.183 +
1.184 +/**
1.185 + * Sets the default string value for an account option.
1.186 + *
1.187 + * @param option The account option.
1.188 + * @param value The default string value.
1.189 + */
1.190 +void purple_account_option_set_default_string(PurpleAccountOption *option,
1.191 + const char *value);
1.192 +
1.193 +/**
1.194 + * Sets the masking for an account option. Setting this to %TRUE acts
1.195 + * as a hint to the UI that the option's value should be obscured from
1.196 + * view, like a password.
1.197 + *
1.198 + * @param option The account option.
1.199 + * @param masked The masking.
1.200 + */
1.201 +void
1.202 +purple_account_option_set_masked(PurpleAccountOption *option, gboolean masked);
1.203 +
1.204 +/**
1.205 + * Sets the list values for an account option.
1.206 + *
1.207 + * The list passed will be owned by the account option, and the
1.208 + * strings inside will be freed automatically.
1.209 + *
1.210 + * The list is in key, value pairs. The key is the ID stored and used
1.211 + * internally, and the value is the label displayed.
1.212 + *
1.213 + * @param option The account option.
1.214 + * @param values The default list value.
1.215 + */
1.216 +void purple_account_option_set_list(PurpleAccountOption *option, GList *values);
1.217 +
1.218 +/**
1.219 + * Adds an item to a list account option.
1.220 + *
1.221 + * @param option The account option.
1.222 + * @param key The key.
1.223 + * @param value The value.
1.224 + */
1.225 +void purple_account_option_add_list_item(PurpleAccountOption *option,
1.226 + const char *key, const char *value);
1.227 +
1.228 +/**
1.229 + * Returns the specified account option's type.
1.230 + *
1.231 + * @param option The account option.
1.232 + *
1.233 + * @return The account option's type.
1.234 + */
1.235 +PurplePrefType purple_account_option_get_type(const PurpleAccountOption *option);
1.236 +
1.237 +/**
1.238 + * Returns the text for an account option.
1.239 + *
1.240 + * @param option The account option.
1.241 + *
1.242 + * @return The account option's text.
1.243 + */
1.244 +const char *purple_account_option_get_text(const PurpleAccountOption *option);
1.245 +
1.246 +/**
1.247 + * Returns the name of an account option. This corresponds to the @c pref_name
1.248 + * parameter supplied to purple_account_option_new() or one of the
1.249 + * type-specific constructors.
1.250 + *
1.251 + * @param option The account option.
1.252 + *
1.253 + * @return The option's name.
1.254 + */
1.255 +const char *purple_account_option_get_setting(const PurpleAccountOption *option);
1.256 +
1.257 +/**
1.258 + * Returns the default boolean value for an account option.
1.259 + *
1.260 + * @param option The account option.
1.261 + *
1.262 + * @return The default boolean value.
1.263 + */
1.264 +gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
1.265 +
1.266 +/**
1.267 + * Returns the default integer value for an account option.
1.268 + *
1.269 + * @param option The account option.
1.270 + *
1.271 + * @return The default integer value.
1.272 + */
1.273 +int purple_account_option_get_default_int(const PurpleAccountOption *option);
1.274 +
1.275 +/**
1.276 + * Returns the default string value for an account option.
1.277 + *
1.278 + * @param option The account option.
1.279 + *
1.280 + * @return The default string value.
1.281 + */
1.282 +const char *purple_account_option_get_default_string(
1.283 + const PurpleAccountOption *option);
1.284 +
1.285 +/**
1.286 + * Returns the default string value for a list account option.
1.287 + *
1.288 + * @param option The account option.
1.289 + *
1.290 + * @return The default list string value.
1.291 + */
1.292 +const char *purple_account_option_get_default_list_value(
1.293 + const PurpleAccountOption *option);
1.294 +
1.295 +/**
1.296 + * Returns whether an option's value should be masked from view, like a
1.297 + * password. If so, the UI might display each character of the option
1.298 + * as a '*' (for example).
1.299 + *
1.300 + * @param option The account option.
1.301 + *
1.302 + * @return %TRUE if the option's value should be obscured.
1.303 + */
1.304 +gboolean
1.305 +purple_account_option_get_masked(const PurpleAccountOption *option);
1.306 +
1.307 +/**
1.308 + * Returns the list values for an account option.
1.309 + *
1.310 + * @param option The account option.
1.311 + *
1.312 + * @constreturn A list of #PurpleKeyValuePair, mapping the human-readable
1.313 + * description of the value to the <tt>(const char *)</tt> that
1.314 + * should be passed to purple_account_set_string() to set the
1.315 + * option.
1.316 + */
1.317 +GList *purple_account_option_get_list(const PurpleAccountOption *option);
1.318 +
1.319 +/*@}*/
1.320 +
1.321 +
1.322 +/**************************************************************************/
1.323 +/** @name Account User Split API */
1.324 +/**************************************************************************/
1.325 +/*@{*/
1.326 +
1.327 +/**
1.328 + * Creates a new account username split.
1.329 + *
1.330 + * @param text The text of the option.
1.331 + * @param default_value The default value.
1.332 + * @param sep The field separator.
1.333 + *
1.334 + * @return The new user split.
1.335 + */
1.336 +PurpleAccountUserSplit *purple_account_user_split_new(const char *text,
1.337 + const char *default_value,
1.338 + char sep);
1.339 +
1.340 +/**
1.341 + * Destroys an account username split.
1.342 + *
1.343 + * @param split The split to destroy.
1.344 + */
1.345 +void purple_account_user_split_destroy(PurpleAccountUserSplit *split);
1.346 +
1.347 +/**
1.348 + * Returns the text for an account username split.
1.349 + *
1.350 + * @param split The account username split.
1.351 + *
1.352 + * @return The account username split's text.
1.353 + */
1.354 +const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split);
1.355 +
1.356 +/**
1.357 + * Returns the default string value for an account split.
1.358 + *
1.359 + * @param split The account username split.
1.360 + *
1.361 + * @return The default string.
1.362 + */
1.363 +const char *purple_account_user_split_get_default_value(
1.364 + const PurpleAccountUserSplit *split);
1.365 +
1.366 +/**
1.367 + * Returns the field separator for an account split.
1.368 + *
1.369 + * @param split The account username split.
1.370 + *
1.371 + * @return The field separator.
1.372 + */
1.373 +char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split);
1.374 +
1.375 +/**
1.376 + * Returns the 'reverse' value for an account split.
1.377 + *
1.378 + * @param split The account username split.
1.379 + *
1.380 + * @return The 'reverse' value.
1.381 + */
1.382 +gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split);
1.383 +
1.384 +/**
1.385 + * Sets the 'reverse' value for an account split.
1.386 + *
1.387 + * @param split The account username split.
1.388 + * @param reverse The 'reverse' value
1.389 + */
1.390 +void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse);
1.391 +
1.392 +/*@}*/
1.393 +
1.394 +#ifdef __cplusplus
1.395 +}
1.396 +#endif
1.397 +
1.398 +#endif /* _PURPLE_ACCOUNTOPT_H_ */