libpurple/accountopt.h

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