1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/prefs.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,362 @@
1.4 +/**
1.5 + * @file prefs.h Prefs API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + *
1.29 + */
1.30 +#ifndef _PURPLE_PREFS_H_
1.31 +#define _PURPLE_PREFS_H_
1.32 +
1.33 +#include <glib.h>
1.34 +
1.35 +/**
1.36 + * Preference data types.
1.37 + */
1.38 +typedef enum _PurplePrefType
1.39 +{
1.40 + PURPLE_PREF_NONE, /**< No type. */
1.41 + PURPLE_PREF_BOOLEAN, /**< Boolean. */
1.42 + PURPLE_PREF_INT, /**< Integer. */
1.43 + PURPLE_PREF_STRING, /**< String. */
1.44 + PURPLE_PREF_STRING_LIST, /**< List of strings. */
1.45 + PURPLE_PREF_PATH, /**< Path. */
1.46 + PURPLE_PREF_PATH_LIST /**< List of paths. */
1.47 +
1.48 +} PurplePrefType;
1.49 +
1.50 +/**
1.51 + * The type of callbacks for preference changes.
1.52 + *
1.53 + * @param name the name of the preference which has changed.
1.54 + * @param type the type of the preferenced named @a name
1.55 + * @param val the new value of the preferencs; should be cast to the correct
1.56 + * type. For instance, to recover the value of a #PURPLE_PREF_INT
1.57 + * preference, use <tt>GPOINTER_TO_INT(val)</tt>. Alternatively,
1.58 + * just call purple_prefs_get_int(), purple_prefs_get_string_list()
1.59 + * etc.
1.60 + * @param data Arbitrary data specified when the callback was connected with
1.61 + * purple_prefs_connect_callback().
1.62 + *
1.63 + * @see purple_prefs_connect_callback()
1.64 + */
1.65 +typedef void (*PurplePrefCallback) (const char *name, PurplePrefType type,
1.66 + gconstpointer val, gpointer data);
1.67 +
1.68 +#ifdef __cplusplus
1.69 +extern "C" {
1.70 +#endif
1.71 +
1.72 +/**************************************************************************/
1.73 +/** @name Prefs API
1.74 + Preferences are named according to a directory-like structure.
1.75 + Example: "/plugins/core/potato/is_from_idaho" (probably a boolean) */
1.76 +/**************************************************************************/
1.77 +/*@{*/
1.78 +
1.79 +/**
1.80 + * Returns the prefs subsystem handle.
1.81 + *
1.82 + * @return The prefs subsystem handle.
1.83 + */
1.84 +void *purple_prefs_get_handle(void);
1.85 +
1.86 +/**
1.87 + * Initialize core prefs
1.88 + */
1.89 +void purple_prefs_init(void);
1.90 +
1.91 +/**
1.92 + * Uninitializes the prefs subsystem.
1.93 + */
1.94 +void purple_prefs_uninit(void);
1.95 +
1.96 +/**
1.97 + * Add a new typeless pref.
1.98 + *
1.99 + * @param name The name of the pref
1.100 + */
1.101 +void purple_prefs_add_none(const char *name);
1.102 +
1.103 +/**
1.104 + * Add a new boolean pref.
1.105 + *
1.106 + * @param name The name of the pref
1.107 + * @param value The initial value to set
1.108 + */
1.109 +void purple_prefs_add_bool(const char *name, gboolean value);
1.110 +
1.111 +/**
1.112 + * Add a new integer pref.
1.113 + *
1.114 + * @param name The name of the pref
1.115 + * @param value The initial value to set
1.116 + */
1.117 +void purple_prefs_add_int(const char *name, int value);
1.118 +
1.119 +/**
1.120 + * Add a new string pref.
1.121 + *
1.122 + * @param name The name of the pref
1.123 + * @param value The initial value to set
1.124 + */
1.125 +void purple_prefs_add_string(const char *name, const char *value);
1.126 +
1.127 +/**
1.128 + * Add a new string list pref.
1.129 + *
1.130 + * @param name The name of the pref
1.131 + * @param value The initial value to set
1.132 + * @note This function takes a copy of the strings in the value list. The list
1.133 + * itself and original copies of the strings are up to the caller to
1.134 + * free.
1.135 + */
1.136 +void purple_prefs_add_string_list(const char *name, GList *value);
1.137 +
1.138 +/**
1.139 + * Add a new path pref.
1.140 + *
1.141 + * @param name The name of the pref
1.142 + * @param value The initial value to set
1.143 + */
1.144 +void purple_prefs_add_path(const char *name, const char *value);
1.145 +
1.146 +/**
1.147 + * Add a new path list pref.
1.148 + *
1.149 + * @param name The name of the pref
1.150 + * @param value The initial value to set
1.151 + * @note This function takes a copy of the strings in the value list. The list
1.152 + * itself and original copies of the strings are up to the caller to
1.153 + * free.
1.154 + */
1.155 +void purple_prefs_add_path_list(const char *name, GList *value);
1.156 +
1.157 +
1.158 +/**
1.159 + * Remove a pref.
1.160 + *
1.161 + * @param name The name of the pref
1.162 + */
1.163 +void purple_prefs_remove(const char *name);
1.164 +
1.165 +/**
1.166 + * Rename a pref
1.167 + *
1.168 + * @param oldname The old name of the pref
1.169 + * @param newname The new name for the pref
1.170 + */
1.171 +void purple_prefs_rename(const char *oldname, const char *newname);
1.172 +
1.173 +/**
1.174 + * Rename a boolean pref, toggling it's value
1.175 + *
1.176 + * @param oldname The old name of the pref
1.177 + * @param newname The new name for the pref
1.178 + */
1.179 +void purple_prefs_rename_boolean_toggle(const char *oldname, const char *newname);
1.180 +
1.181 +/**
1.182 + * Remove all prefs.
1.183 + */
1.184 +void purple_prefs_destroy(void);
1.185 +
1.186 +/**
1.187 + * Set raw pref value
1.188 + *
1.189 + * @param name The name of the pref
1.190 + * @param value The value to set
1.191 + */
1.192 +void purple_prefs_set_generic(const char *name, gpointer value);
1.193 +
1.194 +/**
1.195 + * Set boolean pref value
1.196 + *
1.197 + * @param name The name of the pref
1.198 + * @param value The value to set
1.199 + */
1.200 +void purple_prefs_set_bool(const char *name, gboolean value);
1.201 +
1.202 +/**
1.203 + * Set integer pref value
1.204 + *
1.205 + * @param name The name of the pref
1.206 + * @param value The value to set
1.207 + */
1.208 +void purple_prefs_set_int(const char *name, int value);
1.209 +
1.210 +/**
1.211 + * Set string pref value
1.212 + *
1.213 + * @param name The name of the pref
1.214 + * @param value The value to set
1.215 + */
1.216 +void purple_prefs_set_string(const char *name, const char *value);
1.217 +
1.218 +/**
1.219 + * Set string list pref value
1.220 + *
1.221 + * @param name The name of the pref
1.222 + * @param value The value to set
1.223 + */
1.224 +void purple_prefs_set_string_list(const char *name, GList *value);
1.225 +
1.226 +/**
1.227 + * Set path pref value
1.228 + *
1.229 + * @param name The name of the pref
1.230 + * @param value The value to set
1.231 + */
1.232 +void purple_prefs_set_path(const char *name, const char *value);
1.233 +
1.234 +/**
1.235 + * Set path list pref value
1.236 + *
1.237 + * @param name The name of the pref
1.238 + * @param value The value to set
1.239 + */
1.240 +void purple_prefs_set_path_list(const char *name, GList *value);
1.241 +
1.242 +
1.243 +/**
1.244 + * Check if a pref exists
1.245 + *
1.246 + * @param name The name of the pref
1.247 + * @return TRUE if the pref exists. Otherwise FALSE.
1.248 + */
1.249 +gboolean purple_prefs_exists(const char *name);
1.250 +
1.251 +/**
1.252 + * Get pref type
1.253 + *
1.254 + * @param name The name of the pref
1.255 + * @return The type of the pref
1.256 + */
1.257 +PurplePrefType purple_prefs_get_type(const char *name);
1.258 +
1.259 +/**
1.260 + * Get boolean pref value
1.261 + *
1.262 + * @param name The name of the pref
1.263 + * @return The value of the pref
1.264 + */
1.265 +gboolean purple_prefs_get_bool(const char *name);
1.266 +
1.267 +/**
1.268 + * Get integer pref value
1.269 + *
1.270 + * @param name The name of the pref
1.271 + * @return The value of the pref
1.272 + */
1.273 +int purple_prefs_get_int(const char *name);
1.274 +
1.275 +/**
1.276 + * Get string pref value
1.277 + *
1.278 + * @param name The name of the pref
1.279 + * @return The value of the pref
1.280 + */
1.281 +const char *purple_prefs_get_string(const char *name);
1.282 +
1.283 +/**
1.284 + * Get string list pref value
1.285 + *
1.286 + * @param name The name of the pref
1.287 + * @return The value of the pref
1.288 + */
1.289 +GList *purple_prefs_get_string_list(const char *name);
1.290 +
1.291 +/**
1.292 + * Get path pref value
1.293 + *
1.294 + * @param name The name of the pref
1.295 + * @return The value of the pref
1.296 + */
1.297 +const char *purple_prefs_get_path(const char *name);
1.298 +
1.299 +/**
1.300 + * Get path list pref value
1.301 + *
1.302 + * @param name The name of the pref
1.303 + * @return The value of the pref
1.304 + */
1.305 +GList *purple_prefs_get_path_list(const char *name);
1.306 +
1.307 +/**
1.308 + * Returns a list of children for a pref
1.309 + *
1.310 + * @param name The parent pref
1.311 + * @return A list of newly allocated strings denoting the names of the children.
1.312 + * Returns @c NULL if there are no children or if pref doesn't exist.
1.313 + * The caller must free all the strings and the list.
1.314 + *
1.315 + * @since 2.1.0
1.316 + */
1.317 +GList *purple_prefs_get_children_names(const char *name);
1.318 +
1.319 +/**
1.320 + * Add a callback to a pref (and its children)
1.321 + *
1.322 + * @param handle The handle of the receiver.
1.323 + * @param name The name of the preference
1.324 + * @param cb The callback function
1.325 + * @param data The data to pass to the callback function.
1.326 + *
1.327 + * @return An id to disconnect the callback
1.328 + *
1.329 + * @see purple_prefs_disconnect_callback
1.330 + */
1.331 +guint purple_prefs_connect_callback(void *handle, const char *name, PurplePrefCallback cb,
1.332 + gpointer data);
1.333 +
1.334 +/**
1.335 + * Remove a callback to a pref
1.336 + */
1.337 +void purple_prefs_disconnect_callback(guint callback_id);
1.338 +
1.339 +/**
1.340 + * Remove all pref callbacks by handle
1.341 + */
1.342 +void purple_prefs_disconnect_by_handle(void *handle);
1.343 +
1.344 +/**
1.345 + * Trigger callbacks as if the pref changed
1.346 + */
1.347 +void purple_prefs_trigger_callback(const char *name);
1.348 +
1.349 +/**
1.350 + * Read preferences
1.351 + */
1.352 +gboolean purple_prefs_load(void);
1.353 +
1.354 +/**
1.355 + * Rename legacy prefs and delete some that no longer exist.
1.356 + */
1.357 +void purple_prefs_update_old(void);
1.358 +
1.359 +/*@}*/
1.360 +
1.361 +#ifdef __cplusplus
1.362 +}
1.363 +#endif
1.364 +
1.365 +#endif /* _PURPLE_PREFS_H_ */