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