summaryrefslogtreecommitdiff
path: root/gconf/gconf-client.h
blob: 2b527928d7b9cbc2ad3a9f0485cec31df170d5c8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
/* -*- 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