libpurple/accountopt.h

   1 /**
   2  * @file accountopt.h Account Options API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_ACCOUNTOPT_H_
  27 #define _PURPLE_ACCOUNTOPT_H_
  28
  29 #include "prefs.h"
  30
  31 /**
  32  * An option for an account.
  33  *
  34  * This is set by protocol plugins, and appears in the account settings
  35  * dialogs.
  36  */
  37 typedef struct
  38 {
  39         PurplePrefType type;      /**< The type of value.                     */
  40
  41         char *text;             /**< The text that will appear to the user. */
  42         char *pref_name;        /**< The name of the associated preference. */
  43
  44         union
  45         {
  46                 gboolean boolean;   /**< The default boolean value.             */
  47                 int integer;        /**< The default integer value.             */
  48                 char *string;       /**< The default string value.              */
  49                 GList *list;        /**< The default list value.                */
  50
  51         } default_value;
  52
  53         gboolean masked;        /**< Whether the value entered should be
  54                                  *   obscured from view (for passwords and
  55                                  *   similar options)
  56                                  */
  57 } PurpleAccountOption;
  58
  59 /**
  60  * A username split.
  61  *
  62  * This is used by some protocols to separate the fields of the username
  63  * into more human-readable components.
  64  */
  65 typedef struct
  66 {
  67         char *text;             /**< The text that will appear to the user. */
  68         char *default_value;    /**< The default value.                     */
  69         char  field_sep;        /**< The field separator.                   */
  70         gboolean reverse;       /**< TRUE if the separator should be found
  71                                                           starting a the end of the string, FALSE
  72                                                           otherwise                                 */
  73
  74 } PurpleAccountUserSplit;
  75
  76 #ifdef __cplusplus
  77 extern "C" {
  78 #endif
  79
  80 /**************************************************************************/
  81 /** @name Account Option API                                              */
  82 /**************************************************************************/
  83 /*@{*/
  84
  85 /**
  86  * Creates a new account option.  If you know what @a type will be in advance,
  87  * consider using purple_account_option_bool_new(),
  88  * purple_account_option_int_new(), purple_account_option_string_new() or
  89  * purple_account_option_list_new() (as appropriate) instead.
  90  *
  91  * @param type      The type of option.
  92  * @param text      The text of the option.
  93  * @param pref_name The account preference name for the option.
  94  *
  95  * @return The account option.
  96  */
  97 PurpleAccountOption *purple_account_option_new(PurplePrefType type,
  98         const char *text, const char *pref_name);
  99
 100 /**
 101  * Creates a new boolean account option.
 102  *
 103  * @param text          The text of the option.
 104  * @param pref_name     The account preference name for the option.
 105  * @param default_value The default value.
 106  *
 107  * @return The account option.
 108  */
 109 PurpleAccountOption *purple_account_option_bool_new(const char *text,
 110         const char *pref_name, gboolean default_value);
 111
 112 /**
 113  * Creates a new integer account option.
 114  *
 115  * @param text          The text of the option.
 116  * @param pref_name     The account preference name for the option.
 117  * @param default_value The default value.
 118  *
 119  * @return The account option.
 120  */
 121 PurpleAccountOption *purple_account_option_int_new(const char *text,
 122         const char *pref_name, int default_value);
 123
 124 /**
 125  * Creates a new string account option.
 126  *
 127  * @param text          The text of the option.
 128  * @param pref_name     The account preference name for the option.
 129  * @param default_value The default value.
 130  *
 131  * @return The account option.
 132  */
 133 PurpleAccountOption *purple_account_option_string_new(const char *text,
 134         const char *pref_name, const char *default_value);
 135
 136 /**
 137  * Creates a new list account option.
 138  *
 139  * The list passed will be owned by the account option, and the
 140  * strings inside will be freed automatically.
 141  *
 142  * The list is a list of #PurpleKeyValuePair items. The key is the label that
 143  * should be displayed to the user, and the <tt>(const char *)</tt> value is
 144  * the internal ID that should be passed to purple_account_set_string() to
 145  * choose that value.
 146  *
 147  * @param text      The text of the option.
 148  * @param pref_name The account preference name for the option.
 149  * @param list      The key, value list.
 150  *
 151  * @return The account option.
 152  */
 153 PurpleAccountOption *purple_account_option_list_new(const char *text,
 154         const char *pref_name, GList *list);
 155
 156 /**
 157  * Destroys an account option.
 158  *
 159  * @param option The option to destroy.
 160  */
 161 void purple_account_option_destroy(PurpleAccountOption *option);
 162
 163 /**
 164  * Sets the default boolean value for an account option.
 165  *
 166  * @param option The account option.
 167  * @param value  The default boolean value.
 168  */
 169 void purple_account_option_set_default_bool(PurpleAccountOption *option,
 170                                                                                   gboolean value);
 171
 172 /**
 173  * Sets the default integer value for an account option.
 174  *
 175  * @param option The account option.
 176  * @param value  The default integer value.
 177  */
 178 void purple_account_option_set_default_int(PurpleAccountOption *option,
 179                                                                                  int value);
 180
 181 /**
 182  * Sets the default string value for an account option.
 183  *
 184  * @param option The account option.
 185  * @param value  The default string value.
 186  */
 187 void purple_account_option_set_default_string(PurpleAccountOption *option,
 188                                                                                         const char *value);
 189
 190 /**
 191  * Sets the masking for an account option. Setting this to %TRUE acts
 192  * as a hint to the UI that the option's value should be obscured from
 193  * view, like a password.
 194  *
 195  * @param option The account option.
 196  * @param masked The masking.
 197  */
 198 void
 199 purple_account_option_set_masked(PurpleAccountOption *option, gboolean masked);
 200
 201 /**
 202  * Sets the list values for an account option.
 203  *
 204  * The list passed will be owned by the account option, and the
 205  * strings inside will be freed automatically.
 206  *
 207  * The list is in key, value pairs. The key is the ID stored and used
 208  * internally, and the value is the label displayed.
 209  *
 210  * @param option The account option.
 211  * @param values The default list value.
 212  */
 213 void purple_account_option_set_list(PurpleAccountOption *option, GList *values);
 214
 215 /**
 216  * Adds an item to a list account option.
 217  *
 218  * @param option The account option.
 219  * @param key    The key.
 220  * @param value  The value.
 221  */
 222 void purple_account_option_add_list_item(PurpleAccountOption *option,
 223                                                                            const char *key, const char *value);
 224
 225 /**
 226  * Returns the specified account option's type.
 227  *
 228  * @param option The account option.
 229  *
 230  * @return The account option's type.
 231  */
 232 PurplePrefType purple_account_option_get_type(const PurpleAccountOption *option);
 233
 234 /**
 235  * Returns the text for an account option.
 236  *
 237  * @param option The account option.
 238  *
 239  * @return The account option's text.
 240  */
 241 const char *purple_account_option_get_text(const PurpleAccountOption *option);
 242
 243 /**
 244  * Returns the name of an account option.  This corresponds to the @c pref_name
 245  * parameter supplied to purple_account_option_new() or one of the
 246  * type-specific constructors.
 247  *
 248  * @param option The account option.
 249  *
 250  * @return The option's name.
 251  */
 252 const char *purple_account_option_get_setting(const PurpleAccountOption *option);
 253
 254 /**
 255  * Returns the default boolean value for an account option.
 256  *
 257  * @param option The account option.
 258  *
 259  * @return The default boolean value.
 260  */
 261 gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
 262
 263 /**
 264  * Returns the default integer value for an account option.
 265  *
 266  * @param option The account option.
 267  *
 268  * @return The default integer value.
 269  */
 270 int purple_account_option_get_default_int(const PurpleAccountOption *option);
 271
 272 /**
 273  * Returns the default string value for an account option.
 274  *
 275  * @param option The account option.
 276  *
 277  * @return The default string value.
 278  */
 279 const char *purple_account_option_get_default_string(
 280         const PurpleAccountOption *option);
 281
 282 /**
 283  * Returns the default string value for a list account option.
 284  *
 285  * @param option The account option.
 286  *
 287  * @return The default list string value.
 288  */
 289 const char *purple_account_option_get_default_list_value(
 290         const PurpleAccountOption *option);
 291
 292 /**
 293  * Returns whether an option's value should be masked from view, like a
 294  * password.  If so, the UI might display each character of the option
 295  * as a '*' (for example).
 296  *
 297  * @param option The account option.
 298  *
 299  * @return %TRUE if the option's value should be obscured.
 300  */
 301 gboolean
 302 purple_account_option_get_masked(const PurpleAccountOption *option);
 303
 304 /**
 305  * Returns the list values for an account option.
 306  *
 307  * @param option The account option.
 308  *
 309  * @constreturn A list of #PurpleKeyValuePair, mapping the human-readable
 310  *              description of the value to the <tt>(const char *)</tt> that
 311  *              should be passed to purple_account_set_string() to set the
 312  *              option.
 313  */
 314 GList *purple_account_option_get_list(const PurpleAccountOption *option);
 315
 316 /*@}*/
 317
 318
 319 /**************************************************************************/
 320 /** @name Account User Split API                                          */
 321 /**************************************************************************/
 322 /*@{*/
 323
 324 /**
 325  * Creates a new account username split.
 326  *
 327  * @param text          The text of the option.
 328  * @param default_value The default value.
 329  * @param sep           The field separator.
 330  *
 331  * @return The new user split.
 332  */
 333 PurpleAccountUserSplit *purple_account_user_split_new(const char *text,
 334                                                                                                   const char *default_value,
 335                                                                                                   char sep);
 336
 337 /**
 338  * Destroys an account username split.
 339  *
 340  * @param split The split to destroy.
 341  */
 342 void purple_account_user_split_destroy(PurpleAccountUserSplit *split);
 343
 344 /**
 345  * Returns the text for an account username split.
 346  *
 347  * @param split The account username split.
 348  *
 349  * @return The account username split's text.
 350  */
 351 const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split);
 352
 353 /**
 354  * Returns the default string value for an account split.
 355  *
 356  * @param split The account username split.
 357  *
 358  * @return The default string.
 359  */
 360 const char *purple_account_user_split_get_default_value(
 361                 const PurpleAccountUserSplit *split);
 362
 363 /**
 364  * Returns the field separator for an account split.
 365  *
 366  * @param split The account username split.
 367  *
 368  * @return The field separator.
 369  */
 370 char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split);
 371
 372 /**
 373  * Returns the 'reverse' value for an account split.
 374  *
 375  * @param split The account username split.
 376  *
 377  * @return The 'reverse' value.
 378  */
 379 gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split);
 380
 381 /**
 382  * Sets the 'reverse' value for an account split.
 383  *
 384  * @param split   The account username split.
 385  * @param reverse The 'reverse' value
 386  */
 387 void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse);
 388
 389 /*@}*/
 390
 391 #ifdef __cplusplus
 392 }
 393 #endif
 394
 395 #endif /* _PURPLE_ACCOUNTOPT_H_ */