1.1 --- a/Frameworks/libpurple.framework/Versions/0.6.0/Headers/accountopt.h Fri Aug 21 13:24:36 2009 -0700
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,395 +0,0 @@
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_ */