Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/accountopt.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     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_ */