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 /** 66 * Opaque type to carry callback information 67 * 68 * @since 2.11.0 69 */ 70 typedef struct _PurplePrefCallbackData PurplePrefCallbackData; 71 72 73 /** @copydoc _PurplePrefsUiOps */ 74 typedef struct _PurplePrefsUiOps PurplePrefsUiOps; 75 76 77 /** 78 * Prefs UI operations. This allows overriding the prefs.xml storage with 79 * anything else. 80 * 81 * Unless specified otherwise, each entry provides an implementation for the 82 * corresponding purple_prefs_* method, and disables the prefs.xml code for it. 83 * This means that to do anything useful, all the methods must be implemented. 84 * 85 * @since 2.11.0 86 */ 87 struct _PurplePrefsUiOps 88 { 89 void (*add_none)(const char *name); 90 void (*add_bool)(const char *name, gboolean value); 91 void (*add_int)(const char *name, int value); 92 void (*add_string)(const char *name, const char *value); 93 void (*add_string_list)(const char *name, GList *value); 94 95 void (*set_bool)(const char *name, gboolean value); 96 void (*set_int)(const char *name, int value); 97 void (*set_string)(const char *name, const char *value); 98 void (*set_string_list)(const char *name, GList *value); 99 100 gboolean (*get_bool)(const char *name); 101 int (*get_int)(const char *name); 102 const char *(*get_string)(const char *name); 103 GList *(*get_string_list)(const char *name); 104 105 PurplePrefType (*get_type)(const char *name); 106 GList *(*get_children_names)(const char *name); 107 108 gboolean (*exists)(const char *name); 109 void (*remove)(const char *name); 110 111 void (*rename)(const char *oldname, const char *newname); 112 void (*rename_boolean_toggle)(const char *oldname, const char *newname); 113 114 gboolean (*load)(void); 115 void (*save)(void); 116 void (*schedule_save)(void); 117 118 /** 119 * Called when a callback is added to a preference. The UI must keep 120 * track of it and call #purple_prefs_trigger_callback_object with the 121 * data attribute. 122 * 123 * @param name The preference name. 124 * @param data The object to be passed when triggering the callback 125 * @return A pointer to a ui_data object. 126 * */ 127 void *(*connect_callback)(const char *name, PurplePrefCallbackData *data); 128 129 /** 130 * Called when a callback is removed from a preference. The ui_data 131 * object is the one returned from connect_callback. 132 * 133 * @param name The preference name 134 * @param ui_data The object that was returned from the 135 * connect_callback UI OP. 136 * */ 137 void (*disconnect_callback)(const char *name, void *ui_data); 138 139 void (*_purple_reserved1)(void); 140 void (*_purple_reserved2)(void); 141 void (*_purple_reserved3)(void); 142 void (*_purple_reserved4)(void); 143 void (*_purple_reserved5)(void); 144 }; 145 146 147 148 #ifdef __cplusplus 149 extern "C" { 150 #endif 151 152 /**************************************************************************/ 153 /** @name UI Registration Functions */ 154 /**************************************************************************/ 155 /*@{*/ 156 /** 157 * Sets the UI operations structure to be used for preferences. 158 * 159 * @param ops The UI operations structure. 160 * @since 2.11.0 161 */ 162 void purple_prefs_set_ui_ops(PurplePrefsUiOps *ops); 163 164 /** 165 * Returns the UI operations structure used for preferences. 166 * 167 * @return The UI operations structure in use. 168 * @since 2.11.0 169 */ 170 PurplePrefsUiOps *purple_prefs_get_ui_ops(void); 171 172 /*@}*/ 173 174 /**************************************************************************/ 175 /** @name Prefs API 176 Preferences are named according to a directory-like structure. 177 Example: "/plugins/core/potato/is_from_idaho" (probably a boolean) */ 178 /**************************************************************************/ 179 /*@{*/ 180 181 /** 182 * Returns the prefs subsystem handle. 183 * 184 * @return The prefs subsystem handle. 185 */ 186 void *purple_prefs_get_handle(void); 187 188 /** 189 * Initialize core prefs 190 */ 191 void purple_prefs_init(void); 192 193 /** 194 * Uninitializes the prefs subsystem. 195 */ 196 void purple_prefs_uninit(void); 197 198 /** 199 * Add a new typeless pref. 200 * 201 * @param name The name of the pref 202 */ 203 void purple_prefs_add_none(const char *name); 204 205 /** 206 * Add a new boolean pref. 207 * 208 * @param name The name of the pref 209 * @param value The initial value to set 210 */ 211 void purple_prefs_add_bool(const char *name, gboolean value); 212 213 /** 214 * Add a new integer pref. 215 * 216 * @param name The name of the pref 217 * @param value The initial value to set 218 */ 219 void purple_prefs_add_int(const char *name, int value); 220 221 /** 222 * Add a new string pref. 223 * 224 * @param name The name of the pref 225 * @param value The initial value to set 226 */ 227 void purple_prefs_add_string(const char *name, const char *value); 228 229 /** 230 * Add a new string list pref. 231 * 232 * @param name The name of the pref 233 * @param value The initial value to set 234 * @note This function takes a copy of the strings in the value list. The list 235 * itself and original copies of the strings are up to the caller to 236 * free. 237 */ 238 void purple_prefs_add_string_list(const char *name, GList *value); 239 240 /** 241 * Add a new path pref. 242 * 243 * @param name The name of the pref 244 * @param value The initial value to set 245 */ 246 void purple_prefs_add_path(const char *name, const char *value); 247 248 /** 249 * Add a new path list pref. 250 * 251 * @param name The name of the pref 252 * @param value The initial value to set 253 * @note This function takes a copy of the strings in the value list. The list 254 * itself and original copies of the strings are up to the caller to 255 * free. 256 */ 257 void purple_prefs_add_path_list(const char *name, GList *value); 258 259 260 /** 261 * Remove a pref. 262 * 263 * @param name The name of the pref 264 */ 265 void purple_prefs_remove(const char *name); 266 267 /** 268 * Rename a pref 269 * 270 * @param oldname The old name of the pref 271 * @param newname The new name for the pref 272 */ 273 void purple_prefs_rename(const char *oldname, const char *newname); 274 275 /** 276 * Rename a boolean pref, toggling it's value 277 * 278 * @param oldname The old name of the pref 279 * @param newname The new name for the pref 280 */ 281 void purple_prefs_rename_boolean_toggle(const char *oldname, const char *newname); 282 283 /** 284 * Remove all prefs. 285 */ 286 void purple_prefs_destroy(void); 287 288 /** 289 * Set raw pref value 290 * 291 * @param name The name of the pref 292 * @param value The value to set 293 * 294 * @deprecated We're not really sure what purpose this function serves, so it 295 * will be removed in 3.0.0. Preferences values set using this 296 * function aren't serialized to prefs.xml, which could be 297 * misleading. There is also no purple_prefs_get_generic, which 298 * means that if you can't really get the value (other in a 299 * connected callback). If you think you have a use for this then 300 * please let us know. 301 */ 302 /* TODO: When this is removed, also remove struct purple_pref->value.generic */ 303 void purple_prefs_set_generic(const char *name, gpointer value); 304 305 /** 306 * Set boolean pref value 307 * 308 * @param name The name of the pref 309 * @param value The value to set 310 */ 311 void purple_prefs_set_bool(const char *name, gboolean value); 312 313 /** 314 * Set integer pref value 315 * 316 * @param name The name of the pref 317 * @param value The value to set 318 */ 319 void purple_prefs_set_int(const char *name, int value); 320 321 /** 322 * Set string pref value 323 * 324 * @param name The name of the pref 325 * @param value The value to set 326 */ 327 void purple_prefs_set_string(const char *name, const char *value); 328 329 /** 330 * Set string list pref value 331 * 332 * @param name The name of the pref 333 * @param value The value to set 334 */ 335 void purple_prefs_set_string_list(const char *name, GList *value); 336 337 /** 338 * Set path pref value 339 * 340 * @param name The name of the pref 341 * @param value The value to set 342 */ 343 void purple_prefs_set_path(const char *name, const char *value); 344 345 /** 346 * Set path list pref value 347 * 348 * @param name The name of the pref 349 * @param value The value to set 350 */ 351 void purple_prefs_set_path_list(const char *name, GList *value); 352 353 354 /** 355 * Check if a pref exists 356 * 357 * @param name The name of the pref 358 * @return TRUE if the pref exists. Otherwise FALSE. 359 */ 360 gboolean purple_prefs_exists(const char *name); 361 362 /** 363 * Get pref type 364 * 365 * @param name The name of the pref 366 * @return The type of the pref 367 */ 368 PurplePrefType purple_prefs_get_type(const char *name); 369 370 /** 371 * Get boolean pref value 372 * 373 * @param name The name of the pref 374 * @return The value of the pref 375 */ 376 gboolean purple_prefs_get_bool(const char *name); 377 378 /** 379 * Get integer pref value 380 * 381 * @param name The name of the pref 382 * @return The value of the pref 383 */ 384 int purple_prefs_get_int(const char *name); 385 386 /** 387 * Get string pref value 388 * 389 * @param name The name of the pref 390 * @return The value of the pref 391 */ 392 const char *purple_prefs_get_string(const char *name); 393 394 /** 395 * Get string list pref value 396 * 397 * @param name The name of the pref 398 * @return The value of the pref 399 */ 400 GList *purple_prefs_get_string_list(const char *name); 401 402 /** 403 * Get path pref value 404 * 405 * @param name The name of the pref 406 * @return The value of the pref 407 */ 408 const char *purple_prefs_get_path(const char *name); 409 410 /** 411 * Get path list pref value 412 * 413 * @param name The name of the pref 414 * @return The value of the pref 415 */ 416 GList *purple_prefs_get_path_list(const char *name); 417 418 /** 419 * Returns a list of children for a pref 420 * 421 * @param name The parent pref 422 * @return A list of newly allocated strings denoting the names of the children. 423 * Returns @c NULL if there are no children or if pref doesn't exist. 424 * The caller must free all the strings and the list. 425 * 426 * @since 2.1.0 427 */ 428 GList *purple_prefs_get_children_names(const char *name); 429 430 /** 431 * Add a callback to a pref (and its children) 432 * 433 * @param handle The handle of the receiver. 434 * @param name The name of the preference 435 * @param cb The callback function 436 * @param data The data to pass to the callback function. 437 * 438 * @return An id to disconnect the callback 439 * 440 * @see purple_prefs_disconnect_callback 441 */ 442 guint purple_prefs_connect_callback(void *handle, const char *name, PurplePrefCallback cb, 443 gpointer data); 444 445 /** 446 * Remove a callback to a pref 447 */ 448 void purple_prefs_disconnect_callback(guint callback_id); 449 450 /** 451 * Remove all pref callbacks by handle 452 */ 453 void purple_prefs_disconnect_by_handle(void *handle); 454 455 /** 456 * Trigger callbacks as if the pref changed 457 */ 458 void purple_prefs_trigger_callback(const char *name); 459 460 /** 461 * Trigger callbacks as if the pref changed, taking a #PurplePrefCallbackData 462 * instead of a name 463 * 464 * @since 2.11.0 465 */ 466 void purple_prefs_trigger_callback_object(PurplePrefCallbackData *data); 467 468 469 /** 470 * Read preferences 471 */ 472 gboolean purple_prefs_load(void); 473 474 /** 475 * Rename legacy prefs and delete some that no longer exist. 476 */ 477 void purple_prefs_update_old(void); 478 479 /*@}*/ 480 481 #ifdef __cplusplus 482 } 483 #endif 484 485 #endif /* _PURPLE_PREFS_H_ */ 486