libpurple/prefs.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  *
  21  */
  22
  23 #ifndef PURPLE_PREFS_H
  24 #define PURPLE_PREFS_H
  25 /**
  26  * SECTION:prefs
  27  * @section_id: libpurple-prefs
  28  * @short_description: <filename>prefs.h</filename>
  29  * @title: Preferences API
  30  */
  31
  32 #include <glib.h>
  33
  34 /**
  35  * PurplePrefType:
  36  * @PURPLE_PREF_NONE:        No type.
  37  * @PURPLE_PREF_BOOLEAN:     Boolean.
  38  * @PURPLE_PREF_INT:         Integer.
  39  * @PURPLE_PREF_STRING:      String.
  40  * @PURPLE_PREF_STRING_LIST: List of strings.
  41  * @PURPLE_PREF_PATH:        Path.
  42  * @PURPLE_PREF_PATH_LIST:   List of paths.
  43  *
  44  * Preference data types.
  45  */
  46 typedef enum
  47 {
  48         PURPLE_PREF_NONE,
  49         PURPLE_PREF_BOOLEAN,
  50         PURPLE_PREF_INT,
  51         PURPLE_PREF_STRING,
  52         PURPLE_PREF_STRING_LIST,
  53         PURPLE_PREF_PATH,
  54         PURPLE_PREF_PATH_LIST
  55
  56 } PurplePrefType;
  57
  58 /**
  59  * PurplePrefCallback:
  60  * @name: the name of the preference which has changed.
  61  * @type: the type of the preferenced named @name
  62  * @val:  the new value of the preferencs; should be cast to the correct
  63  *             type.  For instance, to recover the value of a #PURPLE_PREF_INT
  64  *             preference, use <literal>GPOINTER_TO_INT(val)</literal>.
  65  *             Alternatively, just call purple_prefs_get_int(),
  66  *             purple_prefs_get_string_list() etc.
  67  * @data: Arbitrary data specified when the callback was connected with
  68  *             purple_prefs_connect_callback().
  69  *
  70  * The type of callbacks for preference changes.
  71  *
  72  * See purple_prefs_connect_callback().
  73  */
  74 typedef void (*PurplePrefCallback) (const char *name, PurplePrefType type,
  75                 gconstpointer val, gpointer data);
  76
  77 /**
  78  * PurplePrefCallbackData:
  79  *
  80  * Opaque type to carry callback information
  81  *
  82  * Since: 2.11.0
  83  */
  84 typedef struct _PurplePrefCallbackData PurplePrefCallbackData;
  85
  86 typedef struct _PurplePrefsUiOps PurplePrefsUiOps;
  87
  88 /**
  89  * PurplePrefsUiOps:
  90  * @add_none: see #purple_prefs_add_none.
  91  * @add_bool: see #purple_prefs_add_bool.
  92  * @add_int: see #purple_prefs_add_int.
  93  * @add_string: see #purple_prefs_add_string.
  94  * @add_string_list: see #purple_prefs_add_string_list.
  95  * @set_bool: see #purple_prefs_set_bool.
  96  * @set_int: see #purple_prefs_set_int.
  97  * @set_string: see #purple_prefs_set_string.
  98  * @set_string_list: see #purple_prefs_set_string_list.
  99  * @get_bool: see #purple_prefs_get_bool.
 100  * @get_int: see #purple_prefs_get_int.
 101  * @get_string: see #purple_prefs_get_string.
 102  * @get_string_list: see #purple_prefs_get_string_list.
 103  * @get_type: see #purple_prefs_get_type.
 104  * @get_children_names: see #purple_prefs_get_children_names.
 105  * @exists: see #purple_prefs_exists.
 106  * @remove: see #purple_prefs_remove.
 107  * @rename: see #purple_prefs_rename.
 108  * @rename_boolean_toggle: see #purple_prefs_rename_boolean_toggle.
 109  * @load: see #purple_prefs_load.
 110  * @save: see #purple_prefs_save.
 111  * @schedule_save: see #purple_prefs_schedule_save.
 112  * @connect_callback: see #purple_prefs_connect_callback.
 113  * @disconnect_callback: see #purple_prefs_disconnect_callback.
 114  *
 115  * Prefs UI operations. This allows overriding the prefs.xml storage with
 116  * anything else.
 117  *
 118  * Unless specified otherwise, each entry provides an implementation for the
 119  * corresponding purple_prefs_* method, and disables the prefs.xml code for it.
 120  * This means that to do anything useful, all the methods must be implemented.
 121  *
 122  * Since: 2.11.0
 123  */
 124 struct _PurplePrefsUiOps
 125 {
 126         void (*add_none)(const char *name);
 127         void (*add_bool)(const char *name, gboolean value);
 128         void (*add_int)(const char *name, int value);
 129         void (*add_string)(const char *name, const char *value);
 130         void (*add_string_list)(const char *name, GList *value);
 131
 132         void (*set_bool)(const char *name, gboolean value);
 133         void (*set_int)(const char *name, int value);
 134         void (*set_string)(const char *name, const char *value);
 135         void (*set_string_list)(const char *name, GList *value);
 136
 137         gboolean (*get_bool)(const char *name);
 138         int (*get_int)(const char *name);
 139         const char *(*get_string)(const char *name);
 140         GList *(*get_string_list)(const char *name);
 141
 142         PurplePrefType (*get_type)(const char *name);
 143         GList *(*get_children_names)(const char *name);
 144
 145         gboolean (*exists)(const char *name);
 146         void (*remove)(const char *name);
 147
 148         void (*rename)(const char *oldname, const char *newname);
 149         void (*rename_boolean_toggle)(const char *oldname, const char *newname);
 150
 151         gboolean (*load)(void);
 152         void (*save)(void);
 153         void (*schedule_save)(void);
 154
 155         void *(*connect_callback)(const char *name, PurplePrefCallbackData *data);
 156         void (*disconnect_callback)(const char *name, void *ui_data);
 157
 158         /*< private >*/
 159         void (*_purple_reserved1)(void);
 160         void (*_purple_reserved2)(void);
 161         void (*_purple_reserved3)(void);
 162         void (*_purple_reserved4)(void);
 163 };
 164
 165 G_BEGIN_DECLS
 166
 167 /******************************************************************************
 168  * UI Registration Functions
 169  *****************************************************************************/
 170
 171 /**
 172  * purple_prefs_set_ui_ops:
 173  * @ops: The UI operations structure.
 174  *
 175  * Sets the UI operations structure to be used for preferences.
 176  *
 177  * Since: 2.11.0
 178  */
 179 void purple_prefs_set_ui_ops(PurplePrefsUiOps *ops);
 180
 181 /**
 182  * purple_prefs_get_ui_ops:
 183  *
 184  * Returns the UI operations structure used for preferences.
 185  *
 186  * Returns: (transfer none): The UI operations structure in use.
 187  *
 188  * Since: 2.11.0
 189  */
 190 PurplePrefsUiOps *purple_prefs_get_ui_ops(void);
 191
 192 /**************************************************************************/
 193 /*  Prefs API
 194     Preferences are named according to a directory-like structure.
 195     Example: "/plugins/core/potato/is_from_idaho" (probably a boolean)    */
 196 /**************************************************************************/
 197
 198 /**
 199  * purple_prefs_get_handle:
 200  *
 201  * Returns the prefs subsystem handle.
 202  *
 203  * Returns: The prefs subsystem handle.
 204  */
 205 void *purple_prefs_get_handle(void);
 206
 207 /**
 208  * purple_prefs_init:
 209  *
 210  * Initialize core prefs
 211  */
 212 void purple_prefs_init(void);
 213
 214 /**
 215  * purple_prefs_uninit:
 216  *
 217  * Uninitializes the prefs subsystem.
 218  */
 219 void purple_prefs_uninit(void);
 220
 221 /**
 222  * purple_prefs_add_none:
 223  * @name:  The name of the pref
 224  *
 225  * Add a new typeless pref.
 226  */
 227 void purple_prefs_add_none(const char *name);
 228
 229 /**
 230  * purple_prefs_add_bool:
 231  * @name:  The name of the pref
 232  * @value: The initial value to set
 233  *
 234  * Add a new boolean pref.
 235  */
 236 void purple_prefs_add_bool(const char *name, gboolean value);
 237
 238 /**
 239  * purple_prefs_add_int:
 240  * @name:  The name of the pref
 241  * @value: The initial value to set
 242  *
 243  * Add a new integer pref.
 244  */
 245 void purple_prefs_add_int(const char *name, int value);
 246
 247 /**
 248  * purple_prefs_add_string:
 249  * @name:  The name of the pref
 250  * @value: The initial value to set
 251  *
 252  * Add a new string pref.
 253  */
 254 void purple_prefs_add_string(const char *name, const char *value);
 255
 256 /**
 257  * purple_prefs_add_string_list:
 258  * @name:  The name of the pref
 259  * @value: (element-type utf8) (transfer none): The initial value to set
 260  *
 261  * Add a new string list pref.
 262  *
 263  * Note: This function takes a copy of the strings in the value list. The list
 264  *       itself and original copies of the strings are up to the caller to
 265  *       free.
 266  */
 267 void purple_prefs_add_string_list(const char *name, GList *value);
 268
 269 /**
 270  * purple_prefs_add_path:
 271  * @name:  The name of the pref
 272  * @value: The initial value to set
 273  *
 274  * Add a new path pref.
 275  */
 276 void purple_prefs_add_path(const char *name, const char *value);
 277
 278 /**
 279  * purple_prefs_add_path_list:
 280  * @name:  The name of the pref
 281  * @value: (element-type utf8) (transfer none): The initial value to set
 282  *
 283  * Add a new path list pref.
 284  *
 285  * Note: This function takes a copy of the strings in the value list. The list
 286  *       itself and original copies of the strings are up to the caller to
 287  *       free.
 288  */
 289 void purple_prefs_add_path_list(const char *name, GList *value);
 290
 291
 292 /**
 293  * purple_prefs_remove:
 294  * @name: The name of the pref
 295  *
 296  * Remove a pref.
 297  */
 298 void purple_prefs_remove(const char *name);
 299
 300 /**
 301  * purple_prefs_rename:
 302  * @oldname: The old name of the pref
 303  * @newname: The new name for the pref
 304  *
 305  * Rename a pref
 306  */
 307 void purple_prefs_rename(const char *oldname, const char *newname);
 308
 309 /**
 310  * purple_prefs_rename_boolean_toggle:
 311  * @oldname: The old name of the pref
 312  * @newname: The new name for the pref
 313  *
 314  * Rename a boolean pref, toggling it's value
 315  */
 316 void purple_prefs_rename_boolean_toggle(const char *oldname, const char *newname);
 317
 318 /**
 319  * purple_prefs_destroy:
 320  *
 321  * Remove all prefs.
 322  */
 323 void purple_prefs_destroy(void);
 324
 325 /**
 326  * purple_prefs_set_bool:
 327  * @name:  The name of the pref
 328  * @value: The value to set
 329  *
 330  * Set boolean pref value
 331  */
 332 void purple_prefs_set_bool(const char *name, gboolean value);
 333
 334 /**
 335  * purple_prefs_set_int:
 336  * @name:  The name of the pref
 337  * @value: The value to set
 338  *
 339  * Set integer pref value
 340  */
 341 void purple_prefs_set_int(const char *name, int value);
 342
 343 /**
 344  * purple_prefs_set_string:
 345  * @name:  The name of the pref
 346  * @value: The value to set
 347  *
 348  * Set string pref value
 349  */
 350 void purple_prefs_set_string(const char *name, const char *value);
 351
 352 /**
 353  * purple_prefs_set_string_list:
 354  * @name:  The name of the pref
 355  * @value: (element-type utf8) (transfer none): The value to set
 356  *
 357  * Set string list pref value
 358  */
 359 void purple_prefs_set_string_list(const char *name, GList *value);
 360
 361 /**
 362  * purple_prefs_set_path:
 363  * @name:  The name of the pref
 364  * @value: The value to set
 365  *
 366  * Set path pref value
 367  */
 368 void purple_prefs_set_path(const char *name, const char *value);
 369
 370 /**
 371  * purple_prefs_set_path_list:
 372  * @name:  The name of the pref
 373  * @value: (element-type utf8) (transfer none): The value to set
 374  *
 375  * Set path list pref value
 376  */
 377 void purple_prefs_set_path_list(const char *name, GList *value);
 378
 379
 380 /**
 381  * purple_prefs_exists:
 382  * @name: The name of the pref
 383  *
 384  * Check if a pref exists
 385  *
 386  * Returns: TRUE if the pref exists.  Otherwise FALSE.
 387  */
 388 gboolean purple_prefs_exists(const char *name);
 389
 390 /**
 391  * purple_prefs_get_pref_type:
 392  * @name: The name of the pref
 393  *
 394  * Get pref type
 395  *
 396  * Returns: The type of the pref
 397  */
 398 PurplePrefType purple_prefs_get_pref_type(const char *name);
 399
 400 /**
 401  * purple_prefs_get_bool:
 402  * @name: The name of the pref
 403  *
 404  * Get boolean pref value
 405  *
 406  * Returns: The value of the pref
 407  */
 408 gboolean purple_prefs_get_bool(const char *name);
 409
 410 /**
 411  * purple_prefs_get_int:
 412  * @name: The name of the pref
 413  *
 414  * Get integer pref value
 415  *
 416  * Returns: The value of the pref
 417  */
 418 int purple_prefs_get_int(const char *name);
 419
 420 /**
 421  * purple_prefs_get_string:
 422  * @name: The name of the pref
 423  *
 424  * Get string pref value
 425  *
 426  * Returns: The value of the pref
 427  */
 428 const char *purple_prefs_get_string(const char *name);
 429
 430 /**
 431  * purple_prefs_get_string_list:
 432  * @name: The name of the pref
 433  *
 434  * Get string list pref value
 435  *
 436  * Returns: (transfer full) (element-type utf8): The value of the pref.
 437  */
 438 GList *purple_prefs_get_string_list(const char *name);
 439
 440 /**
 441  * purple_prefs_get_path:
 442  * @name: The name of the pref
 443  *
 444  * Get path pref value
 445  *
 446  * Returns: The value of the pref
 447  */
 448 const char *purple_prefs_get_path(const char *name);
 449
 450 /**
 451  * purple_prefs_get_path_list:
 452  * @name: The name of the pref
 453  *
 454  * Get path list pref value
 455  *
 456  * Returns: (transfer full) (element-type utf8): The value of the pref.
 457  */
 458 GList *purple_prefs_get_path_list(const char *name);
 459
 460 /**
 461  * purple_prefs_get_children_names:
 462  * @name: The parent pref
 463  *
 464  * Returns a list of children for a pref
 465  *
 466  * Returns: (transfer full) (element-type utf8): A list of newly allocated
 467  *          strings denoting the names of the children. Returns %NULL if there
 468  *          are no children or if pref doesn't exist. The caller must free all
 469  *          the strings and the list.
 470  */
 471 GList *purple_prefs_get_children_names(const char *name);
 472
 473 /**
 474  * purple_prefs_connect_callback:
 475  * @handle:   The handle of the receiver.
 476  * @name:     The name of the preference
 477  * @cb:       (scope call): The callback function
 478  * @data:     The data to pass to the callback function.
 479  *
 480  * Add a callback to a pref (and its children)
 481  *
 482  * See purple_prefs_disconnect_callback().
 483  *
 484  * Returns: An id to disconnect the callback
 485  */
 486 guint purple_prefs_connect_callback(void *handle, const char *name, PurplePrefCallback cb,
 487                 gpointer data);
 488
 489 /**
 490  * purple_prefs_disconnect_callback:
 491  * @callback_id: The callback_id to disconnect.
 492  *
 493  * Remove a callback to a pref
 494  */
 495 void purple_prefs_disconnect_callback(guint callback_id);
 496
 497 /**
 498  * purple_prefs_disconnect_by_handle:
 499  * @handle: The handle to remove.
 500  *
 501  * Remove all pref callbacks by handle
 502  */
 503 void purple_prefs_disconnect_by_handle(void *handle);
 504
 505 /**
 506  * purple_prefs_trigger_callback:
 507  * @name: The name of the preference.
 508  *
 509  * Trigger callbacks as if the pref changed
 510  */
 511 void purple_prefs_trigger_callback(const char *name);
 512
 513 /**
 514  * purple_prefs_trigger_callback_object:
 515  * @data: Callback data.
 516  *
 517  * Trigger callbacks as if the pref changed, taking a #PurplePrefCallbackData
 518  * instead of a name
 519  *
 520  * Since: 2.11.0
 521  */
 522 void purple_prefs_trigger_callback_object(PurplePrefCallbackData *data);
 523
 524 /**
 525  * purple_prefs_load:
 526  *
 527  * Read preferences
 528  */
 529 gboolean purple_prefs_load(void);
 530
 531 G_END_DECLS
 532
 533 #endif /* PURPLE_PREFS_H */