Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/prefs.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     1 /**
       
     2  * @file prefs.h Prefs 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  */
       
    27 #ifndef _PURPLE_PREFS_H_
       
    28 #define _PURPLE_PREFS_H_
       
    29 
       
    30 #include <glib.h>
       
    31 
       
    32 /**
       
    33  * Preference data types.
       
    34  */
       
    35 typedef enum _PurplePrefType
       
    36 {
       
    37 	PURPLE_PREF_NONE,        /**< No type.         */
       
    38 	PURPLE_PREF_BOOLEAN,     /**< Boolean.         */
       
    39 	PURPLE_PREF_INT,         /**< Integer.         */
       
    40 	PURPLE_PREF_STRING,      /**< String.          */
       
    41 	PURPLE_PREF_STRING_LIST, /**< List of strings. */
       
    42 	PURPLE_PREF_PATH,        /**< Path.            */
       
    43 	PURPLE_PREF_PATH_LIST    /**< List of paths.   */
       
    44 
       
    45 } PurplePrefType;
       
    46 
       
    47 /**
       
    48  * The type of callbacks for preference changes.
       
    49  *
       
    50  * @param name the name of the preference which has changed.
       
    51  * @param type the type of the preferenced named @a name
       
    52  * @param val  the new value of the preferencs; should be cast to the correct
       
    53  *             type.  For instance, to recover the value of a #PURPLE_PREF_INT
       
    54  *             preference, use <tt>GPOINTER_TO_INT(val)</tt>.  Alternatively,
       
    55  *             just call purple_prefs_get_int(), purple_prefs_get_string_list()
       
    56  *             etc.
       
    57  * @param data Arbitrary data specified when the callback was connected with
       
    58  *             purple_prefs_connect_callback().
       
    59  *
       
    60  * @see purple_prefs_connect_callback()
       
    61  */
       
    62 typedef void (*PurplePrefCallback) (const char *name, PurplePrefType type,
       
    63 		gconstpointer val, gpointer data);
       
    64 
       
    65 #ifdef __cplusplus
       
    66 extern "C" {
       
    67 #endif
       
    68 
       
    69 /**************************************************************************/
       
    70 /** @name Prefs API
       
    71     Preferences are named according to a directory-like structure.
       
    72     Example: "/plugins/core/potato/is_from_idaho" (probably a boolean)    */
       
    73 /**************************************************************************/
       
    74 /*@{*/
       
    75 
       
    76 /**
       
    77  * Returns the prefs subsystem handle.
       
    78  *
       
    79  * @return The prefs subsystem handle.
       
    80  */
       
    81 void *purple_prefs_get_handle(void);
       
    82 
       
    83 /**
       
    84  * Initialize core prefs
       
    85  */
       
    86 void purple_prefs_init(void);
       
    87 
       
    88 /**
       
    89  * Uninitializes the prefs subsystem.
       
    90  */
       
    91 void purple_prefs_uninit(void);
       
    92 
       
    93 /**
       
    94  * Add a new typeless pref.
       
    95  *
       
    96  * @param name  The name of the pref
       
    97  */
       
    98 void purple_prefs_add_none(const char *name);
       
    99 
       
   100 /**
       
   101  * Add a new boolean pref.
       
   102  *
       
   103  * @param name  The name of the pref
       
   104  * @param value The initial value to set
       
   105  */
       
   106 void purple_prefs_add_bool(const char *name, gboolean value);
       
   107 
       
   108 /**
       
   109  * Add a new integer pref.
       
   110  *
       
   111  * @param name  The name of the pref
       
   112  * @param value The initial value to set
       
   113  */
       
   114 void purple_prefs_add_int(const char *name, int value);
       
   115 
       
   116 /**
       
   117  * Add a new string pref.
       
   118  *
       
   119  * @param name  The name of the pref
       
   120  * @param value The initial value to set
       
   121  */
       
   122 void purple_prefs_add_string(const char *name, const char *value);
       
   123 
       
   124 /**
       
   125  * Add a new string list pref.
       
   126  *
       
   127  * @param name  The name of the pref
       
   128  * @param value The initial value to set
       
   129  * @note This function takes a copy of the strings in the value list. The list
       
   130  *       itself and original copies of the strings are up to the caller to
       
   131  *       free.
       
   132  */
       
   133 void purple_prefs_add_string_list(const char *name, GList *value);
       
   134 
       
   135 /**
       
   136  * Add a new path pref.
       
   137  *
       
   138  * @param name  The name of the pref
       
   139  * @param value The initial value to set
       
   140  */
       
   141 void purple_prefs_add_path(const char *name, const char *value);
       
   142 
       
   143 /**
       
   144  * Add a new path list pref.
       
   145  *
       
   146  * @param name  The name of the pref
       
   147  * @param value The initial value to set
       
   148  * @note This function takes a copy of the strings in the value list. The list
       
   149  *       itself and original copies of the strings are up to the caller to
       
   150  *       free.
       
   151  */
       
   152 void purple_prefs_add_path_list(const char *name, GList *value);
       
   153 
       
   154 
       
   155 /**
       
   156  * Remove a pref.
       
   157  *
       
   158  * @param name The name of the pref
       
   159  */
       
   160 void purple_prefs_remove(const char *name);
       
   161 
       
   162 /**
       
   163  * Rename a pref
       
   164  *
       
   165  * @param oldname The old name of the pref
       
   166  * @param newname The new name for the pref
       
   167  */
       
   168 void purple_prefs_rename(const char *oldname, const char *newname);
       
   169 
       
   170 /**
       
   171  * Rename a boolean pref, toggling it's value
       
   172  *
       
   173  * @param oldname The old name of the pref
       
   174  * @param newname The new name for the pref
       
   175  */
       
   176 void purple_prefs_rename_boolean_toggle(const char *oldname, const char *newname);
       
   177 
       
   178 /**
       
   179  * Remove all prefs.
       
   180  */
       
   181 void purple_prefs_destroy(void);
       
   182 
       
   183 /**
       
   184  * Set raw pref value
       
   185  *
       
   186  * @param name  The name of the pref
       
   187  * @param value The value to set
       
   188  *
       
   189  * @deprecated We're not really sure what purpose this function serves, so it
       
   190  *             will be removed in 3.0.0.  Preferences values set using this
       
   191  *             function aren't serialized to prefs.xml, which could be
       
   192  *             misleading.  There is also no purple_prefs_get_generic, which
       
   193  *             means that if you can't really get the value (other in a
       
   194  *             connected callback).  If you think you have a use for this then
       
   195  *             please let us know.
       
   196  */
       
   197 /* TODO: When this is removed, also remove struct purple_pref->value.generic */
       
   198 void purple_prefs_set_generic(const char *name, gpointer value);
       
   199 
       
   200 /**
       
   201  * Set boolean pref value
       
   202  *
       
   203  * @param name  The name of the pref
       
   204  * @param value The value to set
       
   205  */
       
   206 void purple_prefs_set_bool(const char *name, gboolean value);
       
   207 
       
   208 /**
       
   209  * Set integer pref value
       
   210  *
       
   211  * @param name  The name of the pref
       
   212  * @param value The value to set
       
   213  */
       
   214 void purple_prefs_set_int(const char *name, int value);
       
   215 
       
   216 /**
       
   217  * Set string pref value
       
   218  *
       
   219  * @param name  The name of the pref
       
   220  * @param value The value to set
       
   221  */
       
   222 void purple_prefs_set_string(const char *name, const char *value);
       
   223 
       
   224 /**
       
   225  * Set string list pref value
       
   226  *
       
   227  * @param name  The name of the pref
       
   228  * @param value The value to set
       
   229  */
       
   230 void purple_prefs_set_string_list(const char *name, GList *value);
       
   231 
       
   232 /**
       
   233  * Set path pref value
       
   234  *
       
   235  * @param name  The name of the pref
       
   236  * @param value The value to set
       
   237  */
       
   238 void purple_prefs_set_path(const char *name, const char *value);
       
   239 
       
   240 /**
       
   241  * Set path list pref value
       
   242  *
       
   243  * @param name  The name of the pref
       
   244  * @param value The value to set
       
   245  */
       
   246 void purple_prefs_set_path_list(const char *name, GList *value);
       
   247 
       
   248 
       
   249 /**
       
   250  * Check if a pref exists
       
   251  *
       
   252  * @param name The name of the pref
       
   253  * @return TRUE if the pref exists.  Otherwise FALSE.
       
   254  */
       
   255 gboolean purple_prefs_exists(const char *name);
       
   256 
       
   257 /**
       
   258  * Get pref type
       
   259  *
       
   260  * @param name The name of the pref
       
   261  * @return The type of the pref
       
   262  */
       
   263 PurplePrefType purple_prefs_get_type(const char *name);
       
   264 
       
   265 /**
       
   266  * Get boolean pref value
       
   267  *
       
   268  * @param name The name of the pref
       
   269  * @return The value of the pref
       
   270  */
       
   271 gboolean purple_prefs_get_bool(const char *name);
       
   272 
       
   273 /**
       
   274  * Get integer pref value
       
   275  *
       
   276  * @param name The name of the pref
       
   277  * @return The value of the pref
       
   278  */
       
   279 int purple_prefs_get_int(const char *name);
       
   280 
       
   281 /**
       
   282  * Get string pref value
       
   283  *
       
   284  * @param name The name of the pref
       
   285  * @return The value of the pref
       
   286  */
       
   287 const char *purple_prefs_get_string(const char *name);
       
   288 
       
   289 /**
       
   290  * Get string list pref value
       
   291  *
       
   292  * @param name The name of the pref
       
   293  * @return The value of the pref
       
   294  */
       
   295 GList *purple_prefs_get_string_list(const char *name);
       
   296 
       
   297 /**
       
   298  * Get path pref value
       
   299  *
       
   300  * @param name The name of the pref
       
   301  * @return The value of the pref
       
   302  */
       
   303 const char *purple_prefs_get_path(const char *name);
       
   304 
       
   305 /**
       
   306  * Get path list pref value
       
   307  *
       
   308  * @param name The name of the pref
       
   309  * @return The value of the pref
       
   310  */
       
   311 GList *purple_prefs_get_path_list(const char *name);
       
   312 
       
   313 /**
       
   314  * Returns a list of children for a pref
       
   315  *
       
   316  * @param name The parent pref
       
   317  * @return A list of newly allocated strings denoting the names of the children.
       
   318  *         Returns @c NULL if there are no children or if pref doesn't exist.
       
   319  *         The caller must free all the strings and the list.
       
   320  *
       
   321  * @since 2.1.0
       
   322  */
       
   323 GList *purple_prefs_get_children_names(const char *name);
       
   324 
       
   325 /**
       
   326  * Add a callback to a pref (and its children)
       
   327  *
       
   328  * @param handle   The handle of the receiver.
       
   329  * @param name     The name of the preference
       
   330  * @param cb       The callback function
       
   331  * @param data     The data to pass to the callback function.
       
   332  *
       
   333  * @return An id to disconnect the callback
       
   334  *
       
   335  * @see purple_prefs_disconnect_callback
       
   336  */
       
   337 guint purple_prefs_connect_callback(void *handle, const char *name, PurplePrefCallback cb,
       
   338 		gpointer data);
       
   339 
       
   340 /**
       
   341  * Remove a callback to a pref
       
   342  */
       
   343 void purple_prefs_disconnect_callback(guint callback_id);
       
   344 
       
   345 /**
       
   346  * Remove all pref callbacks by handle
       
   347  */
       
   348 void purple_prefs_disconnect_by_handle(void *handle);
       
   349 
       
   350 /**
       
   351  * Trigger callbacks as if the pref changed
       
   352  */
       
   353 void purple_prefs_trigger_callback(const char *name);
       
   354 
       
   355 /**
       
   356  * Read preferences
       
   357  */
       
   358 gboolean purple_prefs_load(void);
       
   359 
       
   360 /**
       
   361  * Rename legacy prefs and delete some that no longer exist.
       
   362  */
       
   363 void purple_prefs_update_old(void);
       
   364 
       
   365 /*@}*/
       
   366 
       
   367 #ifdef __cplusplus
       
   368 }
       
   369 #endif
       
   370 
       
   371 #endif /* _PURPLE_PREFS_H_ */