libpurple/prefs.h

   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_ */