gconf_utils.h

Go to the documentation of this file.

#ifndef __GCONF_UTILS_H__
#define __GCONF_UTILS_H__

/**
 * \file gconf_utils.h
 * \brief A lightweight wrapper for gconf library.
 */
 
/*
 * This file is part of liberutils.
 *
 * liberutils is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * liberutils is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * Copyright (C) 2009 iRex Technologies B.V.
 * All rights reserved.
 */
 
//----------------------------------------------------------------------------
// Include Files
//----------------------------------------------------------------------------

// system include files, between < >
#include <glib.h>
#include <gconf/gconf-client.h>

// ereader include files, between < >

// local include files, between " "
#include "er_error.h"

G_BEGIN_DECLS


//----------------------------------------------------------------------------
// Macro Definitions
//---------------------------------------------------------------------------- 


//----------------------------------------------------------------------------
// Forward Declarations
//----------------------------------------------------------------------------


//----------------------------------------------------------------------------
// Type Declarations
//----------------------------------------------------------------------------

typedef void (*gconf_cb_value_changed_t) (const gchar* key, GConfValue* value);


//----------------------------------------------------------------------------
// Global Constants
//----------------------------------------------------------------------------


//============================================================================
// Public Functions
//============================================================================

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_initialize
 *
 * @brief  Initialize GConf client.
 *         Note that GConf client talks to GConf daemon and has no access to
 *         files on disk. Changes are communicated to GConf daemon, who sends
 *         these values to every other client that is interested. The timing
 *         of writing changed values to disk is determined by GConf daemon
 *         and cannot be influenced through a GConf client.
 *
 * @param  --
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_initialize();

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_finalize
 *
 * @brief  Release GConf client.
 *         Note this does not guarantee changes are written to disk now,
 *         because this is determined by the GConf daemon.
 *
 * @param  --
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_finalize();

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_cb_value_changed
 *
 * @brief  Set callback function for gconf value changed
 *
 * @param  [in] callback - Function to be called on a value change in
 *                         one of the directories set with ergconf_add_monitor_dir.
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_set_cb_value_changed(gconf_cb_value_changed_t callback);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_add_monitor_dir
 *
 * @brief  Adds a gconf directory to be monitored.
 *         Value changes in this directory will be reported through the value-changed callback.
 *
 * @param  --
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_add_monitor_dir(const gchar *dir);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_unset
 *
 * @brief  Unset the value of the specified key.
 *         This function clears the value of the key and set it to the default
 *         value defined in the schema file. If schema file doesn't define a
 *         default one then it will be set to gconf default (e.g. for integer
 *         it will be 0).
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_unset(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_recursive_unset
 *
 * @brief  Recursively unset all values in the specified directory and its
 *         sub-directories.
 *         This function clears the value of the keys and sets them to the
 *         default value defined in the schema file. If schema file doesn't
 *         define a default one then it will be set to gconf default (e.g.
 *         for integer it will be 0).
 *
 * @param  [in] dir - The specified directory.
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_recursive_unset(const gchar *dir);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_int
 *
 * @brief  Request the integer value stored at the specified key.
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return The integer value stored at the specified key.
 *
 *--------------------------------------------------------------------------*/
int ergconf_get_int(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_int
 *
 * @brief  Change the value of key to new_value.
 *
 * @param  [in] key - The GConf path of the key.
 *         [in] new_value - The new value to be set.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_int(const gchar* key, int new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_bool
 *
 * @brief  Request the boolean value stored at the specified key.
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return The boolean value stored at the specified key.
 *
 *--------------------------------------------------------------------------*/
gboolean ergconf_get_bool(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_bool
 *
 * @brief  Change the value of key to new_value.
 *
 * @param  [in] key       - The GConf path of the key.
 *         [in] new_value - The new value to be set.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_bool(const gchar* key, gboolean new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_string
 *
 * @brief  Request the string value stored at the specified key.
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return A string value
 *         or NULL on error.
 *         Caller must use g_free() to release this string.
 *
 *--------------------------------------------------------------------------*/
gchar* ergconf_get_string(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_string
 *
 * @brief  Change the value of key to new_value.
 *
 * @param  [in] key       - The GConf path of the key.
 *         [in] new_value - The new value to be set.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_string(const gchar* key, const gchar* new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_string_list
 *
 * @brief  Request the string list value stored at the specified key.
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return A list of strings, each one a gchar* specifying a sub-value of 'key'.
 *         or NULL on error.
 *         Caller must use ergconf_free_string_list() to release this list
 *         and the strings it contains.
 *
 *--------------------------------------------------------------------------*/
GSList* ergconf_get_string_list(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_string_list
 *
 * @brief  Change the value of key to new_value.
 *
 * @param  [in] key       - The GConf path of the key.
 *         [in] new_value - The new value to be set,
 *                          formatted as a list of strings, each one a gchar*.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_string_list(const gchar* key, const GSList *new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_byte_array
 *
 * @brief  Request the byte array value stored at the specified key.
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return A byte array representing the list of integer values stored at 'key'
 *         or NULL on error.
 *         Caller must use g_byte_array_free() to release this byte array.
 *
 *--------------------------------------------------------------------------*/
GByteArray* ergconf_get_byte_array(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_byte_array
 *
 * @brief  Change the value of key to new_value.
 *
 * @param  [in] key       - The GConf path of the key.
 *         [in] new_value - The new value to be set,
 *                          formatted as a byte array.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_byte_array(const gchar* key, const GByteArray *new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_string_hash
 *
 * @brief  Get all key-value pairs from the specified GConf directory
 *         formatted as a hash table.
 *
 * @param  [in] dir - The specified GConf directory.
 *
 * @return A hash table holding all key-value pairs in the specified GConf directory
 *         or NULL on error.
 *         Key   from GConf is used as key in the hash table.
 *         Value from GConf is converted to string and used as value in the hash table.
 *         Caller must use g_hash_table_destroy() to release this hash table.
 *
 *--------------------------------------------------------------------------*/
GHashTable* ergconf_get_string_hash(const gchar* dir);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_string_hash
 *
 * @brief  Set all key-value pairs in the specified GConf directory,
 *         assuming all key-value pairs in this GConf directory are of type string.
 *         Keys not present in new_value will be removed from the GConf directory.
 *         Sub-directories of the GConf directory are not affected.
 *
 * @param  [in] dir       - The specified GConf directory.
 *         [in] new_value - A hash table holding all key-value pairs to be set
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_string_hash(const gchar* dir, const GHashTable *new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_int_array
 *
 * @brief  Get the integer array stored at the specified GConf key.
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return An array holding the integer values stored at this GConf key
 *         or NULL on error.
 *         The array hold elements of type gint.
 *         Caller must use g_array_free() to release this array.
 *
 *--------------------------------------------------------------------------*/
GArray* ergconf_get_int_array(const gchar* key);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_int_array
 *
 * @brief  Change value of specified GConf key into the supplied integer array.
 *
 * @param  [in] key       - The GConf path of the key.
 *         [in] new_value - An array holding 'gint' values to be stored
 *                          at the specified GConf path.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_int_array(const gchar* key, const GArray* new_value);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_int_tuples
 *
 * @brief  Get the list of integer tuples stored at the specified GConf key.
 *
 * @param  [in] key       - The specified GConf key.
 *         [in] tuple_len - Number of integers in a tuple.
 *
 * @return 
 *         An array of integer tuples, each length 'tuple_len',
 *         or NULL on error.
 *         The array holds a set of pointers to a tuple,
 *         each tuple is a GArray of 'guint32' values with length 'tuple_len'.
 *         Caller must use ergconf_free_int_tuples() to release this array
 *         and the integer tuples it contains.
 *
 *--------------------------------------------------------------------------*/
GPtrArray* ergconf_get_int_tuples(const gchar* key, guint tuple_len);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_set_int_tuples
 *
 * @brief  Change value of the specified GConf key into the supplied array
 *         of integer tuples.
 *
 * @param  [in] key       - The specified GConf key.
 *         [in] value     - An array of integer tuples, each length 'tuple_len'.
 *                          The array holds a set of pointers to a tuple,
 *                          each tuple is a GArray of 'guint32' values with length 'tuple_len'.
 *         [in] tuple_len - Number of integers in a tuple.
 *
 * @return ER_OK on success, ER_SET_FAIL on error.
 *
 *--------------------------------------------------------------------------*/
int ergconf_set_int_tuples(const gchar* key, const GPtrArray* value, guint tuple_len);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_free_int_tuples
 *
 * @brief  Free a list of integer tuples
 *
 * @param  [in] tuple_list - An array of integer tuples.
 *                           The array holds a set of pointers to a tuple,
 *                           each tuple is a GArray of 'guint32' values.
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_free_int_tuples(GPtrArray* tuple_list);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_get_sub_dirs
 *
 * @brief  Get a list of sub-directories in the specified GConf directory.
 *
 * @param  [in] dir - The specified GConf directory.
 *
 * @return A list of string, each one a gchar* specifying a sub-directory of 'dir'.
 *         Caller must use ergconf_free_string_list() to release this list
 *         and the strings it contains.
 *
 *--------------------------------------------------------------------------*/
GSList* ergconf_get_sub_dirs(const gchar *dir);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_free_string_list
 *
 * @brief  Free string list returned by e.g. get_value_string_list().
 *
 * @param  [in] str_list  - The string list to be freed.
 *
 * @return --
 *
 *--------------------------------------------------------------------------*/
void ergconf_free_string_list(GSList* str_list);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_dir_exist
 *
 * @brief  Query whether the directory dir exists in the GConf database.
 *
 * @param  [in] dir - The specified directory to be checked.
 *
 * @return TRUE if it exists, FALSE if it doesn't exist.
 *
 *--------------------------------------------------------------------------*/
gboolean ergconf_dir_exist(const gchar* dir);

/**---------------------------------------------------------------------------
 *
 * Name :  ergconf_is_default
 *
 * @brief  Returns if the key is set to the schema default value
 *
 * @param  [in] key - The GConf path of the key.
 *
 * @return TRUE if it is default, FALSE if it doesn't.
 *
 *--------------------------------------------------------------------------*/
gboolean ergconf_is_default(const gchar* key);


G_END_DECLS

#endif  // __GCONF_UTILS_H__