path: root/gconf/gconf-client.h

/* -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* GConf
 * Copyright (C) 1999, 2000 Red Hat Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef GCONF_GCONF_CLIENT_H
#define GCONF_GCONF_CLIENT_H

#include <gtk/gtkobject.h>
#include <gtk/gtkwidget.h>
#include <gconf/gconf.h>
#include <gconf/gconf-listeners.h>
#include <gconf/gconf-changeset.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/*
 * This is a wrapper for the client-side GConf API which provides several
 * convenient features.
 *
 *  - It (recursively) caches the contents of certain directories on
 *    the client side, such as your application's configuration
 *    directory
 *
 *  - It allows you to register per-key callbacks within these directories,
 *    without having to register multiple server-side callbacks
 *    (gconf_engine_notify_add() adds a request-for-notify to the server,
 *    this wrapper adds a notify to the server for the whole directory
 *    and keeps your per-key notify requests on the client side).
 *
 *  - It has some error-handling features
 *
 * This class is heavily specialized for per-user desktop applications -
 * even more so than GConf itself.
 */

/*
 * IMPORTANT: you can't mix GConfClient with direct GConfEngine access,
 * or you will have a mess because the client won't know what you're doing
 * underneath it.
 */

typedef enum {
  GCONF_CLIENT_PRELOAD_NONE,     /* don't preload anything */
  GCONF_CLIENT_PRELOAD_ONELEVEL, /* load entries directly under the directory. */
  GCONF_CLIENT_PRELOAD_RECURSIVE /* recurse the directory tree; possibly quite expensive! */
} GConfClientPreloadType;

typedef enum {
  GCONF_CLIENT_HANDLE_NONE,
  GCONF_CLIENT_HANDLE_UNRETURNED,
  GCONF_CLIENT_HANDLE_ALL
} GConfClientErrorHandlingMode;


typedef struct _GConfClient       GConfClient;
typedef struct _GConfClientClass  GConfClientClass;


typedef void (*GConfClientNotifyFunc)(GConfClient* client, guint cnxn_id, const gchar* key, GConfValue* value, gboolean is_default, gpointer user_data);

/*
 * Return the parent window error dialogs should be associated with, or NULL for
 * none.
 */

typedef GtkWidget* (*GConfClientParentWindowFunc) (GConfClient* client, gpointer user_data);

typedef void (*GConfClientErrorHandlerFunc) (GConfClient* client, GConfClientParentWindowFunc parent_func, gpointer parent_user_data, GError* error);

#define GCONF_TYPE_CLIENT                  (gconf_client_get_type ())
#define GCONF_CLIENT(obj)                  (GTK_CHECK_CAST ((obj), GCONF_TYPE_CLIENT, GConfClient))
#define GCONF_CLIENT_CLASS(klass)          (CONF_CHECK_CLASS_CAST ((klass), GCONF_TYPE_CLIENT, GConfClientClass))
#define GCONF_IS_CLIENT(obj)               (GTK_CHECK_TYPE ((obj), GCONF_TYPE_CLIENT))
#define GCONF_IS_CLIENT_CLASS(klass)       (CONF_CHECK_CLASS_TYPE ((klass), GCONF_TYPE_CLIENT))

struct _GConfClient
{
  GtkObject object;

  /*< private >*/

  GConfEngine* engine;
  GConfClientErrorHandlingMode error_mode;
  GConfClientParentWindowFunc parent_func;
  gpointer parent_user_data;
  GHashTable* dir_hash;
  GHashTable* cache_hash;
  GConfListeners* listeners;
};

struct _GConfClientClass
{
  GtkObjectClass parent_class;

  /* emitted whenever a value changes. Often, you should use a notify
     function instead; the problem with this signal is that you
     probably have to do an expensive chain of strcmp() to
     determine how to respond to it.
  */

  void (* value_changed) (GConfClient* client,
                          const gchar* key,
                          GConfValue* value);

  /* General note about error handling: AVOID DIALOG DELUGES.
     That is, if lots of errors could happen in a row you need
     to collect those and put them in _one_ dialog, maybe using
     an idle function. gconf_client_set_error_handling()
     is provided and it does this using GnomeDialog.  */

  /* emitted when you pass NULL for the error return location to a
     GConfClient function and an error occurs. This allows you to
     ignore errors when your generic handler will work, and handle
     them specifically when you need to */
  void (* unreturned_error) (GConfClient* client,
                             GError* error);

  /* emitted unconditionally anytime there's an error, whether you ask
     for that error or not. Useful for creating an error log or
     something. */
  void (* error)            (GConfClient* client,
                             GError* error);
};


GtkType           gconf_client_get_type        (void);

/* use the default engine */
GConfClient*      gconf_client_get_default             (void);

/* refcount on engine is incremented, you still own your ref */
GConfClient*      gconf_client_get_for_engine (GConfEngine* engine);

/* Add a directory to monitor and emit the value_changed signal and
   key notifications for.  Optionally pre-load the contents of this
   directory, much faster if you plan to access most of the directory
   contents. You can't add overlapping directories.
*/

void              gconf_client_add_dir     (GConfClient* client,
                                            const gchar* dir,
                                            GConfClientPreloadType preload,
                                            GError** err);


/* This removes any notifications associated with the dir */
void              gconf_client_remove_dir  (GConfClient* client,
                                            const gchar* dir,
                                            GError** err);

/*
 *  The notification facility allows you to attach a callback to a single
 *  key or directory, which is more convenient most of the time than
 *  the value_changed signal. The key you're monitoring must be inside one
 *  of the GConfClient's directories.
 */


/* Returns ID of the notification */
/* returns 0 on error, 0 is an invalid ID */
guint        gconf_client_notify_add(GConfClient* client,
                                     const gchar* namespace_section, /* dir or key to listen to */
                                     GConfClientNotifyFunc func,
                                     gpointer user_data,
                                     GFreeFunc destroy_notify,
                                     GError** err);

void         gconf_client_notify_remove  (GConfClient* client,
                                          guint cnxn);

/*
 * Error handling convenience; if you don't want the default handler,
 * set the error handling to GCONF_CLIENT_HANDLE_NONE
 */

/* 
 * Error handling happens in the default signal handler, so you can
 * selectively override the default handling by connecting to the error
 * signal and calling gtk_signal_emit_stop()
 */

void              gconf_client_set_error_handling(GConfClient* client,
                                                  GConfClientErrorHandlingMode mode,
                                                  /* func can be NULL for none or N/A */
                                                  GConfClientParentWindowFunc func,
                                                  gpointer user_data);


/* Intended for use by gnome-libs */
void              gconf_client_set_global_default_error_handler(GConfClientErrorHandlerFunc func);

/*
 * If you know you're done reading values for a while,
 * you can blow away the cache. Note that this nullifies the effect of
 * any preloading you may have done. However it frees some memory.
 */
void              gconf_client_clear_cache(GConfClient* client);

/*
 * Preload a directory; the directory must have been added already.
 * This is only useful as an optimization if you clear the cache,
 * then later want to do a lot of reads again. It's not useful
 * unless you clear the cache, because you can preload when you
 * call gconf_client_add_dir()
 */
void              gconf_client_preload    (GConfClient* client,
                                           const gchar* dirname,
                                           GConfClientPreloadType type,
                                           GError** err);

/*
 * Basic key-manipulation facilities; these keys do _not_ have to be in the
 * client's directory list, but they won't be cached unless they are.
 */

void              gconf_client_set             (GConfClient* client,
                                                const gchar* key,
                                                GConfValue* val,
                                                GError** err);

GConfValue*       gconf_client_get             (GConfClient* client,
                                                const gchar* key,
                                                GError** err);

GConfValue*       gconf_client_get_without_default  (GConfClient* client,
                                                     const gchar* key,
                                                     GError** err);

/* Try not to use this function, it makes me nervous. */
GConfValue*       gconf_client_get_full        (GConfClient* client,
                                                const gchar* key, const gchar* locale,
                                                gboolean use_schema_default,
                                                gboolean* value_is_default,
                                                GError** err);

GConfValue*       gconf_client_get_default_from_schema (GConfClient* client,
                                                        const gchar* key,
                                                        GError** err);

gboolean     gconf_client_unset          (GConfClient* client,
                                          const gchar* key, GError** err);

GSList*      gconf_client_all_entries    (GConfClient* client,
                                          const gchar* dir, GError** err);

GSList*      gconf_client_all_dirs       (GConfClient* client,
                                          const gchar* dir, GError** err);

void         gconf_client_suggest_sync   (GConfClient* client,
                                          GError** err);

gboolean     gconf_client_dir_exists     (GConfClient* client,
                                          const gchar* dir, GError** err);

/* Get/Set convenience wrappers */

gdouble      gconf_client_get_float (GConfClient* client, const gchar* key,
                                     GError** err);

gint         gconf_client_get_int   (GConfClient* client, const gchar* key,
                                     GError** err);

/* free the retval, if non-NULL */
gchar*       gconf_client_get_string(GConfClient* client, const gchar* key,
                                     GError** err);

gboolean     gconf_client_get_bool  (GConfClient* client, const gchar* key,
                                     GError** err);

/* this one has no default since it would be expensive and make little
   sense; it returns NULL as a default, to indicate unset or error */
/* free the retval */
/* Note that this returns the schema stored at key, NOT
   the schema that key conforms to. */
GConfSchema* gconf_client_get_schema  (GConfClient* client,
                                       const gchar* key, GError** err);

GSList*      gconf_client_get_list    (GConfClient* client, const gchar* key,
                                       GConfValueType list_type, GError** err);

gboolean     gconf_client_get_pair    (GConfClient* client, const gchar* key,
                                       GConfValueType car_type, GConfValueType cdr_type,
                                       gpointer car_retloc, gpointer cdr_retloc,
                                       GError** err);

/* No convenience functions for lists or pairs, since there are too
   many combinations of types possible
*/

/* setters return TRUE on success; note that you still should suggest a sync */

gboolean     gconf_client_set_float   (GConfClient* client, const gchar* key,
                                       gdouble val, GError** err);

gboolean     gconf_client_set_int     (GConfClient* client, const gchar* key,
                                       gint val, GError** err);

gboolean     gconf_client_set_string  (GConfClient* client, const gchar* key,
                                       const gchar* val, GError** err);

gboolean     gconf_client_set_bool    (GConfClient* client, const gchar* key,
                                       gboolean val, GError** err);

gboolean     gconf_client_set_schema  (GConfClient* client, const gchar* key,
                                       GConfSchema* val, GError** err);

/* List should be the same as the one gconf_client_get_list() would return */
gboolean     gconf_client_set_list    (GConfClient* client, const gchar* key,
                                       GConfValueType list_type,
                                       GSList* list,
                                       GError** err);

gboolean     gconf_client_set_pair    (GConfClient* client, const gchar* key,
                                       GConfValueType car_type, GConfValueType cdr_type,
                                       gconstpointer address_of_car,
                                       gconstpointer address_of_cdr,
                                       GError** err);

/*
 * Functions to emit signals
 */

/* these are useful to manually invoke the default error handlers */
void         gconf_client_error                  (GConfClient* client, GError* error);
void         gconf_client_unreturned_error       (GConfClient* client, GError* error);

/* useful to force an update */
void         gconf_client_value_changed          (GConfClient* client,
                                                  const gchar* key,
                                                  GConfValue* value);

/*
 * Change set stuff
 */

gboolean        gconf_client_commit_change_set   (GConfClient* client,
                                                  GConfChangeSet* cs,
                                                  /* remove all
                                                     successfully
                                                     committed changes
                                                     from the set */
                                                  gboolean remove_committed,
                                                  GError** err);

/* Create a change set that would revert the given change set
   for the given GConfClient */
GConfChangeSet* gconf_client_reverse_change_set  (GConfClient* client,
                                                         GConfChangeSet* cs,
                                                         GError** err);

GConfChangeSet* gconf_client_change_set_from_currentv (GConfClient* client,
                                                              const gchar** keys,
                                                              GError** err);

GConfChangeSet* gconf_client_change_set_from_current (GConfClient* client,
                                                             GError** err,
                                                             const gchar* first_key,
                                                             ...);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif