1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
7
<!-- ##### SECTION Long_Description ##### -->
12
<!-- ##### SECTION See_Also ##### -->
17
<!-- ##### STRUCT GConfBackendVTable ##### -->
19
The #GConfBackendVTable is a table of methods that any GConf backend must
20
implement. The dynamically loaded library module should export a function
21
called gconf_backend_get_vtable() that returns a pointer to a
26
Here are the methods the backend must implement, and their specification:
28
<informaltable pgwide=1 frame="none">
29
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
33
<entry>@shutdown</entry>
34
<entry>Called prior to unloading the dynamic
35
module. Should ensure that no functions or static/global variables from the
36
module will ever be accessed again. Should free any memory that the backend
42
<entry>@resolve_address</entry>
45
Should create a #GConfSource for accessing the supplied address. Should set the
46
%GCONF_SOURCE_ALL_READABLE and %GCONF_SOURCE_ALL_WRITEABLE flags if
47
appropriate. If these are not set, the backend must implement the @writable and
48
@readable methods. If <symbol>NULL</symbol> is returned, then the error should
57
<entry>If the backend is thread safe (does its own locking or whatever), then
58
@lock and @unlock can be <symbol>NULL</symbol>. If the backend requires a lock
59
for each source, then @lock and @unlock should lock/unlock that lock. If the
60
backend has a global lock for all uses of the backend, then @lock and @unlock
61
should ignore their arguments and lock the entire backend.
68
<entry>@unlock</entry>
69
<entry>See description of @lock.</entry>
74
<entry>@readable</entry>
77
If the %GCONF_SOURCE_ALL_READABLE flag is set, this method is never called and
78
may be <symbol>NULL</symbol>. If %GCONF_SOURCE_ALL_READABLE is unset, and this
79
method is <symbol>NULL</symbol>, then the source is write-only. If this method
80
is implemented, it should return <symbol>TRUE</symbol> if the given key could be
81
read from the given source. <symbol>TRUE</symbol> should be returned even if the
82
key is unset; this function returns something similar to permissions, it is not
83
asking whether the key exists. <emphasis>If an error is set, then
84
<symbol>FALSE</symbol> must be returned.</emphasis>
91
<entry>@writable</entry>
92
<entry>Analagous to @readable, but for writing.</entry>
97
<entry>@query_value</entry>
99
<entry>This method must be implemented if the source is readable. It returns the
100
value of a key. The "locales" argument is a <symbol>NULL</symbol>-terminated
101
vector of locale names, where the first locale in the vector is the preferred
102
locale, the next is the second choice, etc. if the "schema_name" argument is
103
non-<symbol>NULL</symbol>, then it should be filled with an allocated string
104
giving the name of the schema attached to the key, if and only if
105
<symbol>NULL</symbol> is returned. This is an optimization to avoid looking up
106
the same key again in the database if it's unset and we need to ask for its
107
default value from the schema. If <symbol>NULL</symbol> is returned, indicating
108
that the key is unset, then schema_name should not be filled in. If this method
109
sets an error, <symbol>NULL</symbol> must be returned. It may not set an error
110
while also returning a value. The returned value will be destroyed by the
111
caller, so should be a copy of the backend's internal data.
116
<entry>@query_metainfo</entry>
118
<entry>This method must be implemented. If any metainfo is
119
available about a key, it returns a #GConfMetaInfo with that metainfo set. If
120
none is available, <symbol>NULL</symbol> is returned. <symbol>NULL</symbol>
121
should also be returned if an error is set.
128
<entry>@set_value</entry>
130
<entry>This method must be implemented if the source is
131
writable. It sets the value of a key. If the key is already set, its value
132
should be replaced. Setting a value should update the modification time of the
140
<entry>@all_entries</entry>
142
<entry>This method must be implemented. It returns a list of all keys in the
143
given directory for which some information is available (metainfo or
144
values). The returned list should contain #GConfEntry objects. On error,
145
<symbol>NULL</symbol> should be returned and the error set. Subdirectories
146
should not be included in the returned list. The list and the #GConfEntry
147
objects will be freed by the caller.
154
<entry>@all_subdirs</entry>
156
<entry>This method must be implemented. It returns a list of all the subdirectories in a given
157
directory. It should return the subdirectories as relative paths, i.e. there
158
should not be any slashes in the subdirectory name. Each subdirectory in the list
159
should be an allocated string; the list and the strings will be freed by the caller.
166
<entry>@unset_value</entry>
168
<entry>If the given key has a value, then this method should unset the value.
169
If a value is unset, subsequent calls to @query_value should return
170
<symbol>NULL</symbol>. If the locale string passed in to @unset_value is
171
non-<symbol>NULL</symbol>, then only the value for that locale should be
172
unset. If <symbol>NULL</symbol>, the value should be globally unset for all
180
<entry>@dir_exists</entry>
183
Determines whether a directory exists. Should return
184
<symbol>TRUE</symbol> if there is a directory with the given name.
191
<entry>@remove_dir</entry>
194
Should remove a directory, recursively: including all its subdirectories and
195
all the values and keys inside the directory.
202
<entry>@set_schema</entry>
204
<entry>Should associate a schema name with a key.
211
<entry>@sync_all</entry>
214
Should ensure that all data is stored on permanent media, or whatever makes
215
sense for the backend. Called periodically by the GConf daemon.
222
<entry>@destroy_source</entry>
225
Should destroy a source obtained with @resolve_address.
231
</tbody></tgroup></informaltable>
253
<!-- ##### STRUCT GConfBackend ##### -->
263
<!-- ##### FUNCTION gconf_address_backend ##### -->
272
<!-- ##### FUNCTION gconf_address_resource ##### -->
281
<!-- ##### FUNCTION gconf_backend_file ##### -->
290
<!-- ##### FUNCTION gconf_get_backend ##### -->
300
<!-- ##### FUNCTION gconf_backend_ref ##### -->
308
<!-- ##### FUNCTION gconf_backend_unref ##### -->
316
<!-- ##### FUNCTION gconf_backend_resolve_address ##### -->
added
removed
doc/gconf/tmpl/gconf-backend.sgml
