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: (element-type PurpleKeyValuePair) (transfer full): 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: (element-type utf8) (transfer full): 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: (element-type PurpleKeyValuePair) (transfer full): The default list
 206  *          value.
 207  *
 208  * Sets the list values for an account option.
 209  *
 210  * The list passed will be owned by the account option, and the
 211  * strings inside will be freed automatically.
 212  *
 213  * The list is in key, value pairs. The key is the ID stored and used
 214  * internally, and the value is the label displayed.
 215  */
 216 void purple_account_option_set_list(PurpleAccountOption *option, GList *values);
 217
 218 /**
 219  * purple_account_option_add_list_item:
 220  * @option: The account option.
 221  * @key:    The key.
 222  * @value:  The value.
 223  *
 224  * Adds an item to a list account option.
 225  */
 226 void purple_account_option_add_list_item(PurpleAccountOption *option,
 227                                                                            const char *key, const char *value);
 228
 229 /**
 230  * purple_account_option_get_pref_type:
 231  * @option: The account option.
 232  *
 233  * Returns the specified account option's type.
 234  *
 235  * Returns: The account option's type.
 236  */
 237 PurplePrefType purple_account_option_get_pref_type(const PurpleAccountOption *option);
 238
 239 /**
 240  * purple_account_option_get_text:
 241  * @option: The account option.
 242  *
 243  * Returns the text for an account option.
 244  *
 245  * Returns: The account option's text.
 246  */
 247 const char *purple_account_option_get_text(const PurpleAccountOption *option);
 248
 249 /**
 250  * purple_account_option_get_setting:
 251  * @option: The account option.
 252  *
 253  * Returns the name of an account option.  This corresponds to the @c pref_name
 254  * parameter supplied to purple_account_option_new() or one of the
 255  * type-specific constructors.
 256  *
 257  * Returns: The option's name.
 258  */
 259 const char *purple_account_option_get_setting(const PurpleAccountOption *option);
 260
 261 /**
 262  * purple_account_option_get_default_bool:
 263  * @option: The account option.
 264  *
 265  * Returns the default boolean value for an account option.
 266  *
 267  * Returns: The default boolean value.
 268  */
 269 gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
 270
 271 /**
 272  * purple_account_option_get_default_int:
 273  * @option: The account option.
 274  *
 275  * Returns the default integer value for an account option.
 276  *
 277  * Returns: The default integer value.
 278  */
 279 int purple_account_option_get_default_int(const PurpleAccountOption *option);
 280
 281 /**
 282  * purple_account_option_get_default_string:
 283  * @option: The account option.
 284  *
 285  * Returns the default string value for an account option.
 286  *
 287  * Returns: The default string value.
 288  */
 289 const char *purple_account_option_get_default_string(
 290         const PurpleAccountOption *option);
 291
 292 /**
 293  * purple_account_option_get_default_list_value:
 294  * @option: The account option.
 295  *
 296  * Returns the default string value for a list account option.
 297  *
 298  * Returns: The default list string value.
 299  */
 300 const char *purple_account_option_get_default_list_value(
 301         const PurpleAccountOption *option);
 302
 303 /**
 304  * purple_account_option_string_get_masked:
 305  * @option: The account option.
 306  *
 307  * Returns whether an option's value should be masked from view, like a
 308  * password.  If so, the UI might display each character of the option
 309  * as a '*' (for example).
 310  *
 311  * Returns: %TRUE if the option's value should be obscured.
 312  */
 313 gboolean
 314 purple_account_option_string_get_masked(const PurpleAccountOption *option);
 315
 316 /**
 317  * purple_account_option_string_get_hints:
 318  * @option: The account option.
 319  *
 320  * Returns the list of hints for an account option.
 321  *
 322  * Returns: (element-type utf8) (transfer none): A list of hints.
 323  */
 324 const GSList * purple_account_option_string_get_hints(const PurpleAccountOption *option);
 325
 326 /**
 327  * purple_account_option_get_list:
 328  * @option: The account option.
 329  *
 330  * Returns the list values for an account option.
 331  *
 332  * Returns: (element-type PurpleKeyValuePair) (transfer none): A list of
 333  *          #PurpleKeyValuePair, mapping the human-readable description of the
 334  *          value to the <type>(const char *)</type> that should be passed to
 335  *          purple_account_set_string() to set the option.
 336  */
 337 GList *purple_account_option_get_list(const PurpleAccountOption *option);
 338
 339
 340 /**************************************************************************/
 341 /* Account User Split API                                                 */
 342 /**************************************************************************/
 343
 344 /**
 345  * purple_account_user_split_new:
 346  * @text:          The text of the option.
 347  * @default_value: The default value.
 348  * @sep:           The field separator.
 349  *
 350  * Creates a new account username split.
 351  *
 352  * Returns: The new user split.
 353  */
 354 PurpleAccountUserSplit *purple_account_user_split_new(const char *text,
 355                                                                                                   const char *default_value,
 356                                                                                                   char sep);
 357
 358 /**
 359  * purple_account_user_split_destroy:
 360  * @split: The split to destroy.
 361  *
 362  * Destroys an account username split.
 363  */
 364 void purple_account_user_split_destroy(PurpleAccountUserSplit *split);
 365
 366 /**
 367  * purple_account_user_split_get_text:
 368  * @split: The account username split.
 369  *
 370  * Returns the text for an account username split.
 371  *
 372  * Returns: The account username split's text.
 373  */
 374 const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split);
 375
 376 /**
 377  * purple_account_user_split_get_default_value:
 378  * @split: The account username split.
 379  *
 380  * Returns the default string value for an account split.
 381  *
 382  * Returns: The default string.
 383  */
 384 const char *purple_account_user_split_get_default_value(
 385                 const PurpleAccountUserSplit *split);
 386
 387 /**
 388  * purple_account_user_split_get_separator:
 389  * @split: The account username split.
 390  *
 391  * Returns the field separator for an account split.
 392  *
 393  * Returns: The field separator.
 394  */
 395 char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split);
 396
 397 /**
 398  * purple_account_user_split_get_reverse:
 399  * @split: The account username split.
 400  *
 401  * Returns the 'reverse' value for an account split.
 402  *
 403  * Returns: The 'reverse' value.
 404  */
 405 gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split);
 406
 407 /**
 408  * purple_account_user_split_set_reverse:
 409  * @split:   The account username split.
 410  * @reverse: The 'reverse' value
 411  *
 412  * Sets the 'reverse' value for an account split.
 413  */
 414 void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse);
 415
 416 /**
 417  * purple_account_user_split_is_constant:
 418  * @split: The account username split.
 419  *
 420  * Returns the constant parameter for an account split.
 421  *
 422  * When split is constant, it does not need to be displayed
 423  * in configuration dialog.
 424  *
 425  * Returns: %TRUE, if the split is constant.
 426  */
 427 gboolean
 428 purple_account_user_split_is_constant(const PurpleAccountUserSplit *split);
 429
 430 /**
 431  * purple_account_user_split_set_constant:
 432  * @split:    The account username split.
 433  * @constant: %TRUE, if the split is a constant part.
 434  *
 435  * Sets the constant parameter of account split.
 436  */
 437 void
 438 purple_account_user_split_set_constant(PurpleAccountUserSplit *split,
 439         gboolean constant);
 440
 441 G_END_DECLS
 442
 443 #endif /* PURPLE_ACCOUNTOPT_H */