2
* GConf BerkeleyDB back-end
4
* Copyright (C) 2000 Sun Microsystems Inc
5
* Contributed to the GConf project.
7
* This library is free software; you can redistribute it and/or
8
* modify it under the terms of the GNU Library General Public
9
* License as published by the Free Software Foundation; either
10
* version 2 of the License, or (at your option) any later version.
12
* This library 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 GNU
15
* Library General Public License for more details.
17
* You should have received a copy of the GNU Library General Public
18
* License along with this library; if not, write to the
19
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20
* Boston, MA 02111-1307, USA.
26
* A GConf back-end is a storage implementation for the GConf API. Different
27
* back-ends or "drivers" are integrated into GConf using a struct
28
* GConfBackendVTable containing function pointers, simulating a C++
29
* virtual function pointer table (vtable).
31
* This back-end uses the BerkeleyDB database toolkit from Sleepycat
32
* software (www.sleepycat.com). BerkeleyDB is not a relational database,
33
* but is highly suited to GConf as it simply stores key-value pairs and
34
* is relatively efficient.
36
* The storage model if implemented in a relational database would
39
* Directory structure table: { directory_path, id, parent_directory_id }
40
* Keyname/Value table: { key_name, directory_id, value }
42
* A keyname is the last element in the hierarchical key; a directory path
43
* is required to form the complete key - this composition of directory path
44
* and keyname is called a keypath.
46
* Because a BerkeleyDB database can only store a single key+value pair,
47
* this program splits these tables into four databases:
49
* Table: Key | Value: Data?
50
* ----- ----------- ----
51
* BDB_DIR directory_path | directory_id Yes
52
* BDB_HIERARCHY directory_id | child_directory_name No
53
* BDB_KEY directory_id | keyname No
54
* BDB_VALUE keypath | value Yes
55
* BDB_SCHEMA keypath | schema-key Yes
56
* BDB_SCHKEY directory_id | schema-key-name No
58
* A Data table is one that may not have records with identical keys. Other
59
* tables may not contain identical key-value pairs (i.e. two records
60
* could have the same key but must have different values).
63
* Note that an important goal is that all tables could be
64
* reconstructed from the BDB_VALUE table and the BDB_SCHEMA table. This
65
* is possible because the BDB_VALUE table contains the full key-name (the
66
* keypath) and the value, similar to the BDB_SCHEMA table; the other
67
* tables permit the database to be traversed hierarchically instead of
72
* Locale data is stored in a subdirectory of the regular key directory for each
73
* locale; e.g. the Spanish locale data for a key /gnome/desktop/logo is
74
* /gnome/desktop/%locale%es/logo. This allows locale data to be found
75
* efficiently, e.g. the all_entries() backend method accepts a list of
76
* locales to be searched. If the list contains, { "es", "en", "C" }
77
* then the directories searched are /gnome/desktop/, /gnome/desktop/%locale%es,
78
* /gnome/desktop/%locale%en, and /gnome/desktop/%locale%C.
82
* Schemas are stored with regular keys in the BDB_VALUE database, but it
83
* is necessary to search for them specifically. This requires two databases,
84
* BDB_SCHEMA to store the "applyto" key (see the GConf docs) and the schema
85
* key under which the schema can be found. The BDB_SCHKEY is similar to the
86
* BDB_KEY database as it records the keys in each directory for which a
87
* schema value may be found.
91
* GConf doesn't specify any locking functionality at the API level.
92
* Currently locking is a requirement, because workgroups and ultimately
93
* enterprises will require large central GConf databases to store
94
* common settings and defaults for users, although these users will
95
* also require separate writable stores for their personal preferences.
96
* For now, no locking functionality is implemented, but later locking may
97
* be required for individual key-value pairs and for hierarchies. The
98
* BDB_DIR database is locked when updating the highest integer id value
99
* assigned to a directory.
103
* Ideally caching should be independent of any back-end, which can only
104
* be achieved by layering the cache on top of the back-ends rather than
105
* within each one, though this is not always practical/efficient. This
106
* implementation includes minimal caching for database structure, not
107
* for values. Even this caching should be above the back-ends, as it
108
* is time-consuming to find a key and to decide where it should be
109
* stored; if each store in GConf has a base path, then no queries are
110
* needed at run-time to locate keys for read or write.
114
* BerkeleyDB transactions are used to do grouped writes.
125
#include <gconf/gconf.h>
127
#define DBD_DIR "dir.db"
128
#define DBD_HIERARCHY "hierarchy.db"
129
#define DBD_KEY "key.db"
130
#define DBD_VALUE "value.db"
131
#define DBD_SCHEMA "schema.db"
132
#define DBD_SCHKEY "schkey.db"
136
typedef struct _BDB_Store
150
int bdb_create (BDB_Store * bdb, const char *dbname);
152
BDB_Store *bdb_new (const char *dir, int flags);
154
#define CLEAR_STRUCT(x) (memset(&x, 0, sizeof(x)))
156
extern DBT *temp_string_key (const char *key);
157
extern DBT *temp_int_key (int akey);
158
extern guint32 get_dir_id (BDB_Store * bdb, const char *dir);
159
extern void add_key (BDB_Store * bdb, const char *dir, const char *keypath);
160
extern void bdb_set_sysname (const char *name);
161
extern guint32 get_or_create_dir (BDB_Store * bdb, const char *dir);
163
int bdb_create (BDB_Store * bdb, const char *dir);
164
int bdb_open (BDB_Store * bdb, const char *dir, int flags);
165
void bdb_close (BDB_Store * bdb);
167
extern GConfValue *bdb_query_value (BDB_Store * bdb, const char *key,
168
char **schema_name, GError ** err);
170
extern GSList *bdb_all_dirs (BDB_Store * bdb, const char *dirname,
172
extern GSList *bdb_all_entries (BDB_Store * bdb, const char *dirpath,
173
GSList * inlist, GError ** err);
174
extern void bdb_put_value (BDB_Store * bdb, const char *key, GConfValue * val,
176
extern GSList *bdb_all_subdirs (BDB_Store * bdb, const char *dirname,
178
extern void bdb_unset_value (BDB_Store * bdb, const char *keypath,
179
const char *locale, GError ** err);
180
extern void bdb_remove_dir (BDB_Store * bdb, const char *dirname,
182
extern void bdb_set_schema (BDB_Store * bdb, const char *key,
183
const char *schema_key, GError ** err);
185
extern gboolean bdb_is_localised (const gchar * key);
187
#define struct_dup(x) g_memdup(&x, sizeof(x))
added
removed
backends/bdb.h
