Update to version 2.33.1
[profile/ivi/glib2.git] / docs / reference / gio / html / GSettingsBackend.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>GSettingsBackend</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="index.html" title="GIO Reference Manual">
8 <link rel="up" href="settings.html" title="Settings">
9 <link rel="prev" href="GSettings.html" title="GSettings">
10 <link rel="next" href="gio-GSettingsSchema-GSettingsSchemaSource.html" title="GSettingsSchema, GSettingsSchemaSource">
11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
16 <tr valign="middle">
17 <td><a accesskey="p" href="GSettings.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="settings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">GIO Reference Manual</th>
21 <td><a accesskey="n" href="gio-GSettingsSchema-GSettingsSchemaSource.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
22 </tr>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#GSettingsBackend.synopsis" class="shortcut">Top</a>
25                    | 
26                   <a href="#GSettingsBackend.description" class="shortcut">Description</a>
27                    | 
28                   <a href="#GSettingsBackend.object-hierarchy" class="shortcut">Object Hierarchy</a>
29 </td></tr>
30 </table>
31 <div class="refentry">
32 <a name="GSettingsBackend"></a><div class="titlepage"></div>
33 <div class="refnamediv"><table width="100%"><tr>
34 <td valign="top">
35 <h2><span class="refentrytitle"><a name="GSettingsBackend.top_of_page"></a>GSettingsBackend</span></h2>
36 <p>GSettingsBackend — Interface for settings backend implementations</p>
37 </td>
38 <td valign="top" align="right"></td>
39 </tr></table></div>
40 <div class="refsynopsisdiv">
41 <a name="GSettingsBackend.synopsis"></a><h2>Synopsis</h2>
42 <pre class="synopsis">
43 #include &lt;gio/gsettingsbackend.h&gt;
44
45                     <a class="link" href="GSettingsBackend.html#GSettingsBackend-struct" title="GSettingsBackend">GSettingsBackend</a>;
46 struct              <a class="link" href="GSettingsBackend.html#GSettingsBackendClass" title="struct GSettingsBackendClass">GSettingsBackendClass</a>;
47 #define             <a class="link" href="GSettingsBackend.html#G-SETTINGS-BACKEND-EXTENSION-POINT-NAME:CAPS" title="G_SETTINGS_BACKEND_EXTENSION_POINT_NAME">G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</a>
48 <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  <a class="link" href="GSettingsBackend.html#g-settings-backend-get-default" title="g_settings_backend_get_default ()">g_settings_backend_get_default</a>      (<em class="parameter"><code><span class="type">void</span></code></em>);
49 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()">g_settings_backend_changed</a>          (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
50                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *key</code></em>,
51                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);
52 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-path-changed" title="g_settings_backend_path_changed ()">g_settings_backend_path_changed</a>     (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
53                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>,
54                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);
55 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-keys-changed" title="g_settings_backend_keys_changed ()">g_settings_backend_keys_changed</a>     (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
56                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>,
57                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> const * const *items</code></em>,
58                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);
59 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-path-writable-changed" title="g_settings_backend_path_writable_changed ()">g_settings_backend_path_writable_changed</a>
60                                                         (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
61                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>);
62 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-writable-changed" title="g_settings_backend_writable_changed ()">g_settings_backend_writable_changed</a> (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
63                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *key</code></em>);
64 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-changed-tree" title="g_settings_backend_changed_tree ()">g_settings_backend_changed_tree</a>     (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
65                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> *tree</code></em>,
66                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);
67 <span class="returnvalue">void</span>                <a class="link" href="GSettingsBackend.html#g-settings-backend-flatten-tree" title="g_settings_backend_flatten_tree ()">g_settings_backend_flatten_tree</a>     (<em class="parameter"><code><a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> *tree</code></em>,
68                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **path</code></em>,
69                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> ***keys</code></em>,
70                                                          <em class="parameter"><code><a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> ***values</code></em>);
71 <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  <a class="link" href="GSettingsBackend.html#g-keyfile-settings-backend-new" title="g_keyfile_settings_backend_new ()">g_keyfile_settings_backend_new</a>      (<em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *filename</code></em>,
72                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *root_path</code></em>,
73                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *root_group</code></em>);
74 <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  <a class="link" href="GSettingsBackend.html#g-memory-settings-backend-new" title="g_memory_settings_backend_new ()">g_memory_settings_backend_new</a>       (<em class="parameter"><code><span class="type">void</span></code></em>);
75 <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  <a class="link" href="GSettingsBackend.html#g-null-settings-backend-new" title="g_null_settings_backend_new ()">g_null_settings_backend_new</a>         (<em class="parameter"><code><span class="type">void</span></code></em>);
76 </pre>
77 </div>
78 <div class="refsect1">
79 <a name="GSettingsBackend.object-hierarchy"></a><h2>Object Hierarchy</h2>
80 <pre class="synopsis">
81   <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
82    +----GSettingsBackend
83 </pre>
84 </div>
85 <div class="refsect1">
86 <a name="GSettingsBackend.description"></a><h2>Description</h2>
87 <p>
88 The <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> interface defines a generic interface for
89 non-strictly-typed data that is stored in a hierarchy. To implement
90 an alternative storage backend for <a class="link" href="GSettings.html" title="GSettings"><span class="type">GSettings</span></a>, you need to implement
91 the <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> interface and then make it implement the
92 extension point <a class="link" href="GSettingsBackend.html#G-SETTINGS-BACKEND-EXTENSION-POINT-NAME:CAPS" title="G_SETTINGS_BACKEND_EXTENSION_POINT_NAME"><span class="type">G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</span></a>.
93 </p>
94 <p>
95 The interface defines methods for reading and writing values, a
96 method for determining if writing of certain values will fail
97 (lockdown) and a change notification mechanism.
98 </p>
99 <p>
100 The semantics of the interface are very precisely defined and
101 implementations must carefully adhere to the expectations of
102 callers that are documented on each of the interface methods.
103 </p>
104 <p>
105 Some of the GSettingsBackend functions accept or return a <a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a>.
106 These trees always have strings as keys and <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> as values.
107 <code class="function">g_settings_backend_create_tree()</code> is a convenience function to create
108 suitable trees.
109 </p>
110 <p>
111 </p>
112 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
113 <h3 class="title">Note</h3>
114 <p>
115 The <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> API is exported to allow third-party
116 implementations, but does not carry the same stability guarantees
117 as the public GIO API. For this reason, you have to define the
118 C preprocessor symbol <span class="type">G_SETTINGS_ENABLE_BACKEND</span> before including
119 <code class="filename">gio/gsettingsbackend.h</code>
120 </p>
121 </div>
122 <p>
123 </p>
124 </div>
125 <div class="refsect1">
126 <a name="GSettingsBackend.details"></a><h2>Details</h2>
127 <div class="refsect2">
128 <a name="GSettingsBackend-struct"></a><h3>GSettingsBackend</h3>
129 <pre class="programlisting">typedef struct _GSettingsBackend GSettingsBackend;</pre>
130 <p>
131 An implementation of a settings storage repository.
132 </p>
133 </div>
134 <hr>
135 <div class="refsect2">
136 <a name="GSettingsBackendClass"></a><h3>struct GSettingsBackendClass</h3>
137 <pre class="programlisting">struct GSettingsBackendClass {
138   GObjectClass parent_class;
139
140   GVariant *    (*read)             (GSettingsBackend    *backend,
141                                      const gchar         *key,
142                                      const GVariantType  *expected_type,
143                                      gboolean             default_value);
144
145   gboolean      (*get_writable)     (GSettingsBackend    *backend,
146                                      const gchar         *key);
147
148   gboolean      (*write)            (GSettingsBackend    *backend,
149                                      const gchar         *key,
150                                      GVariant            *value,
151                                      gpointer             origin_tag);
152   gboolean      (*write_tree)       (GSettingsBackend    *backend,
153                                      GTree               *tree,
154                                      gpointer             origin_tag);
155   void          (*reset)            (GSettingsBackend    *backend,
156                                      const gchar         *key,
157                                      gpointer             origin_tag);
158
159   void          (*subscribe)        (GSettingsBackend    *backend,
160                                      const gchar         *name);
161   void          (*unsubscribe)      (GSettingsBackend    *backend,
162                                      const gchar         *name);
163   void          (*sync)             (GSettingsBackend    *backend);
164
165   GPermission * (*get_permission)   (GSettingsBackend    *backend,
166                                      const gchar         *path);
167
168   gpointer padding[24];
169 };
170 </pre>
171 </div>
172 <hr>
173 <div class="refsect2">
174 <a name="G-SETTINGS-BACKEND-EXTENSION-POINT-NAME:CAPS"></a><h3>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</h3>
175 <pre class="programlisting">#define G_SETTINGS_BACKEND_EXTENSION_POINT_NAME "gsettings-backend"
176 </pre>
177 <p>
178 Extension point for <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> functionality.
179 </p>
180 </div>
181 <hr>
182 <div class="refsect2">
183 <a name="g-settings-backend-get-default"></a><h3>g_settings_backend_get_default ()</h3>
184 <pre class="programlisting"><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  g_settings_backend_get_default      (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
185 <p>
186 Returns the default <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. It is possible to override
187 the default by setting the <code class="envar">GSETTINGS_BACKEND</code>
188 environment variable to the name of a settings backend.
189 </p>
190 <p>
191 The user gets a reference to the backend.
192 </p>
193 <div class="variablelist"><table border="0">
194 <col align="left" valign="top">
195 <tbody><tr>
196 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
197 <td>the default <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
198 </td>
199 </tr></tbody>
200 </table></div>
201 <p class="since">Since 2.28</p>
202 </div>
203 <hr>
204 <div class="refsect2">
205 <a name="g-settings-backend-changed"></a><h3>g_settings_backend_changed ()</h3>
206 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_changed          (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
207                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *key</code></em>,
208                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre>
209 <p>
210 Signals that a single key has possibly changed.  Backend
211 implementations should call this if a key has possibly changed its
212 value.
213 </p>
214 <p>
215 <em class="parameter"><code>key</code></em> must be a valid key (ie starting with a slash, not containing
216 '//', and not ending with a slash).
217 </p>
218 <p>
219 The implementation must call this function during any call to
220 <code class="function">g_settings_backend_write()</code>, before the call returns (except in the
221 case that no keys are actually changed and it cares to detect this
222 fact).  It may not rely on the existence of a mainloop for
223 dispatching the signal later.
224 </p>
225 <p>
226 The implementation may call this function at any other time it likes
227 in response to other events (such as changes occurring outside of the
228 program).  These calls may originate from a mainloop or may originate
229 in response to any other action (including from calls to
230 <code class="function">g_settings_backend_write()</code>).
231 </p>
232 <p>
233 In the case that this call is in response to a call to
234 <code class="function">g_settings_backend_write()</code> then <em class="parameter"><code>origin_tag</code></em> must be set to the same
235 value that was passed to that call.
236 </p>
237 <div class="variablelist"><table border="0">
238 <col align="left" valign="top">
239 <tbody>
240 <tr>
241 <td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
242 <td>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</td>
243 </tr>
244 <tr>
245 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
246 <td>the name of the key</td>
247 </tr>
248 <tr>
249 <td><p><span class="term"><em class="parameter"><code>origin_tag</code></em> :</span></p></td>
250 <td>the origin tag</td>
251 </tr>
252 </tbody>
253 </table></div>
254 <p class="since">Since 2.26</p>
255 </div>
256 <hr>
257 <div class="refsect2">
258 <a name="g-settings-backend-path-changed"></a><h3>g_settings_backend_path_changed ()</h3>
259 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_path_changed     (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
260                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>,
261                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre>
262 <p>
263 Signals that all keys below a given path may have possibly changed.
264 Backend implementations should call this if an entire path of keys
265 have possibly changed their values.
266 </p>
267 <p>
268 <em class="parameter"><code>path</code></em> must be a valid path (ie starting and ending with a slash and
269 not containing '//').
270 </p>
271 <p>
272 The meaning of this signal is that any of the key which has a name
273 starting with <em class="parameter"><code>path</code></em> may have changed.
274 </p>
275 <p>
276 The same rules for when notifications must occur apply as per
277 <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()"><code class="function">g_settings_backend_changed()</code></a>.  This call might be an appropriate
278 reasponse to a 'reset' call but implementations are also free to
279 explicitly list the keys that were affected by that call if they can
280 easily do so.
281 </p>
282 <p>
283 For efficiency reasons, the implementation should strive for <em class="parameter"><code>path</code></em> to
284 be as long as possible (ie: the longest common prefix of all of the
285 keys that were changed) but this is not strictly required.  As an
286 example, if this function is called with the path of "/" then every
287 single key in the application will be notified of a possible change.
288 </p>
289 <div class="variablelist"><table border="0">
290 <col align="left" valign="top">
291 <tbody>
292 <tr>
293 <td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
294 <td>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</td>
295 </tr>
296 <tr>
297 <td><p><span class="term"><em class="parameter"><code>path</code></em> :</span></p></td>
298 <td>the path containing the changes</td>
299 </tr>
300 <tr>
301 <td><p><span class="term"><em class="parameter"><code>origin_tag</code></em> :</span></p></td>
302 <td>the origin tag</td>
303 </tr>
304 </tbody>
305 </table></div>
306 <p class="since">Since 2.26</p>
307 </div>
308 <hr>
309 <div class="refsect2">
310 <a name="g-settings-backend-keys-changed"></a><h3>g_settings_backend_keys_changed ()</h3>
311 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_keys_changed     (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
312                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>,
313                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> const * const *items</code></em>,
314                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre>
315 <p>
316 Signals that a list of keys have possibly changed.  Backend
317 implementations should call this if keys have possibly changed their
318 values.
319 </p>
320 <p>
321 <em class="parameter"><code>path</code></em> must be a valid path (ie starting and ending with a slash and
322 not containing '//').  Each string in <em class="parameter"><code>items</code></em> must form a valid key
323 name when <em class="parameter"><code>path</code></em> is prefixed to it (ie: each item must not start or
324 end with '/' and must not contain '//').
325 </p>
326 <p>
327 The meaning of this signal is that any of the key names resulting
328 from the contatenation of <em class="parameter"><code>path</code></em> with each item in <em class="parameter"><code>items</code></em> may have
329 changed.
330 </p>
331 <p>
332 The same rules for when notifications must occur apply as per
333 <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()"><code class="function">g_settings_backend_changed()</code></a>.  These two calls can be used
334 interchangeably if exactly one item has changed (although in that
335 case <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()"><code class="function">g_settings_backend_changed()</code></a> is definitely preferred).
336 </p>
337 <p>
338 For efficiency reasons, the implementation should strive for <em class="parameter"><code>path</code></em> to
339 be as long as possible (ie: the longest common prefix of all of the
340 keys that were changed) but this is not strictly required.
341 </p>
342 <div class="variablelist"><table border="0">
343 <col align="left" valign="top">
344 <tbody>
345 <tr>
346 <td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
347 <td>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</td>
348 </tr>
349 <tr>
350 <td><p><span class="term"><em class="parameter"><code>path</code></em> :</span></p></td>
351 <td>the path containing the changes</td>
352 </tr>
353 <tr>
354 <td><p><span class="term"><em class="parameter"><code>items</code></em> :</span></p></td>
355 <td>the <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated list of changed keys. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span>
356 </td>
357 </tr>
358 <tr>
359 <td><p><span class="term"><em class="parameter"><code>origin_tag</code></em> :</span></p></td>
360 <td>the origin tag</td>
361 </tr>
362 </tbody>
363 </table></div>
364 <p class="since">Since 2.26</p>
365 </div>
366 <hr>
367 <div class="refsect2">
368 <a name="g-settings-backend-path-writable-changed"></a><h3>g_settings_backend_path_writable_changed ()</h3>
369 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_path_writable_changed
370                                                         (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
371                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>);</pre>
372 <p>
373 Signals that the writability of all keys below a given path may have
374 changed.
375 </p>
376 <p>
377 Since GSettings performs no locking operations for itself, this call
378 will always be made in response to external events.
379 </p>
380 <div class="variablelist"><table border="0">
381 <col align="left" valign="top">
382 <tbody>
383 <tr>
384 <td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
385 <td>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</td>
386 </tr>
387 <tr>
388 <td><p><span class="term"><em class="parameter"><code>path</code></em> :</span></p></td>
389 <td>the name of the path</td>
390 </tr>
391 </tbody>
392 </table></div>
393 <p class="since">Since 2.26</p>
394 </div>
395 <hr>
396 <div class="refsect2">
397 <a name="g-settings-backend-writable-changed"></a><h3>g_settings_backend_writable_changed ()</h3>
398 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_writable_changed (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
399                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *key</code></em>);</pre>
400 <p>
401 Signals that the writability of a single key has possibly changed.
402 </p>
403 <p>
404 Since GSettings performs no locking operations for itself, this call
405 will always be made in response to external events.
406 </p>
407 <div class="variablelist"><table border="0">
408 <col align="left" valign="top">
409 <tbody>
410 <tr>
411 <td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
412 <td>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</td>
413 </tr>
414 <tr>
415 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
416 <td>the name of the key</td>
417 </tr>
418 </tbody>
419 </table></div>
420 <p class="since">Since 2.26</p>
421 </div>
422 <hr>
423 <div class="refsect2">
424 <a name="g-settings-backend-changed-tree"></a><h3>g_settings_backend_changed_tree ()</h3>
425 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_changed_tree     (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>,
426                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> *tree</code></em>,
427                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre>
428 <p>
429 This call is a convenience wrapper.  It gets the list of changes from
430 <em class="parameter"><code>tree</code></em>, computes the longest common prefix and calls
431 <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()"><code class="function">g_settings_backend_changed()</code></a>.
432 </p>
433 <div class="variablelist"><table border="0">
434 <col align="left" valign="top">
435 <tbody>
436 <tr>
437 <td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
438 <td>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</td>
439 </tr>
440 <tr>
441 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
442 <td>a <a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> containing the changes</td>
443 </tr>
444 <tr>
445 <td><p><span class="term"><em class="parameter"><code>origin_tag</code></em> :</span></p></td>
446 <td>the origin tag</td>
447 </tr>
448 </tbody>
449 </table></div>
450 <p class="since">Since 2.26</p>
451 </div>
452 <hr>
453 <div class="refsect2">
454 <a name="g-settings-backend-flatten-tree"></a><h3>g_settings_backend_flatten_tree ()</h3>
455 <pre class="programlisting"><span class="returnvalue">void</span>                g_settings_backend_flatten_tree     (<em class="parameter"><code><a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> *tree</code></em>,
456                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **path</code></em>,
457                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> ***keys</code></em>,
458                                                          <em class="parameter"><code><a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> ***values</code></em>);</pre>
459 <p>
460 Calculate the longest common prefix of all keys in a tree and write
461 out an array of the key names relative to that prefix and,
462 optionally, the value to store at each of those keys.
463 </p>
464 <p>
465 You must free the value returned in <em class="parameter"><code>path</code></em>, <em class="parameter"><code>keys</code></em> and <em class="parameter"><code>values</code></em> using
466 <a href="./../glib/glib/glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>.  You should not attempt to free or unref the contents of
467 <em class="parameter"><code>keys</code></em> or <em class="parameter"><code>values</code></em>.
468 </p>
469 <div class="variablelist"><table border="0">
470 <col align="left" valign="top">
471 <tbody>
472 <tr>
473 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
474 <td>a <a href="./../glib/glib/glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> containing the changes</td>
475 </tr>
476 <tr>
477 <td><p><span class="term"><em class="parameter"><code>path</code></em> :</span></p></td>
478 <td>the location to save the path. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span>
479 </td>
480 </tr>
481 <tr>
482 <td><p><span class="term"><em class="parameter"><code>keys</code></em> :</span></p></td>
483 <td>the
484 location to save the relative keys. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Free data container after the code is done."><span class="acronym">transfer container</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span>
485 </td>
486 </tr>
487 <tr>
488 <td><p><span class="term"><em class="parameter"><code>values</code></em> :</span></p></td>
489 <td>the location to save the values, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Free data container after the code is done."><span class="acronym">transfer container</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span>
490 </td>
491 </tr>
492 </tbody>
493 </table></div>
494 <p class="since">Since 2.26</p>
495 </div>
496 <hr>
497 <div class="refsect2">
498 <a name="g-keyfile-settings-backend-new"></a><h3>g_keyfile_settings_backend_new ()</h3>
499 <pre class="programlisting"><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  g_keyfile_settings_backend_new      (<em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *filename</code></em>,
500                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *root_path</code></em>,
501                                                          <em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *root_group</code></em>);</pre>
502 <p>
503 Creates a keyfile-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.
504 </p>
505 <p>
506 The filename of the keyfile to use is given by <em class="parameter"><code>filename</code></em>.
507 </p>
508 <p>
509 All settings read to or written from the backend must fall under the
510 path given in <em class="parameter"><code>root_path</code></em> (which must start and end with a slash and
511 not contain two consecutive slashes).  <em class="parameter"><code>root_path</code></em> may be "/".
512 </p>
513 <p>
514 If <em class="parameter"><code>root_group</code></em> is non-<a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it specifies the name of the keyfile
515 group used for keys that are written directly below <em class="parameter"><code>root_path</code></em>.  For
516 example, if <em class="parameter"><code>root_path</code></em> is "/apps/example/" and <em class="parameter"><code>root_group</code></em> is
517 "toplevel", then settings the key "/apps/example/enabled" to a value
518 of <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> will cause the following to appear in the keyfile:
519 </p>
520 <p>
521 </p>
522 <div class="informalexample"><pre class="programlisting">
523   [toplevel]
524   enabled=true
525 </pre></div>
526 <p>
527 </p>
528 <p>
529 If <em class="parameter"><code>root_group</code></em> is <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it is not permitted to store keys
530 directly below the <em class="parameter"><code>root_path</code></em>.
531 </p>
532 <p>
533 For keys not stored directly below <em class="parameter"><code>root_path</code></em> (ie: in a sub-path),
534 the name of the subpath (with the final slash stripped) is used as
535 the name of the keyfile group.  To continue the example, if
536 "/apps/example/profiles/default/font-size" were set to
537 12 then the following would appear in the keyfile:
538 </p>
539 <p>
540 </p>
541 <div class="informalexample"><pre class="programlisting">
542   [profiles/default]
543   font-size=12
544 </pre></div>
545 <p>
546 </p>
547 <p>
548 The backend will refuse writes (and return writability as being
549 <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>) for keys outside of <em class="parameter"><code>root_path</code></em> and, in the event that
550 <em class="parameter"><code>root_group</code></em> is <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, also for keys directly under <em class="parameter"><code>root_path</code></em>.
551 Writes will also be refused if the backend detects that it has the
552 inability to rewrite the keyfile (ie: the containing directory is not
553 writable).
554 </p>
555 <p>
556 There is no checking done for your key namespace clashing with the
557 syntax of the key file format.  For example, if you have '[' or ']'
558 characters in your path names or '=' in your key names you may be in
559 trouble.
560 </p>
561 <div class="variablelist"><table border="0">
562 <col align="left" valign="top">
563 <tbody>
564 <tr>
565 <td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
566 <td>the filename of the keyfile</td>
567 </tr>
568 <tr>
569 <td><p><span class="term"><em class="parameter"><code>root_path</code></em> :</span></p></td>
570 <td>the path under which all settings keys appear</td>
571 </tr>
572 <tr>
573 <td><p><span class="term"><em class="parameter"><code>root_group</code></em> :</span></p></td>
574 <td>the group name corresponding to
575 <em class="parameter"><code>root_path</code></em>, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
576 </td>
577 </tr>
578 <tr>
579 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
580 <td>a keyfile-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
581 </td>
582 </tr>
583 </tbody>
584 </table></div>
585 </div>
586 <hr>
587 <div class="refsect2">
588 <a name="g-memory-settings-backend-new"></a><h3>g_memory_settings_backend_new ()</h3>
589 <pre class="programlisting"><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  g_memory_settings_backend_new       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
590 <p>
591 Creates a memory-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.
592 </p>
593 <p>
594 This backend allows changes to settings, but does not write them
595 to any backing storage, so the next time you run your application,
596 the memory backend will start out with the default values again.
597 </p>
598 <div class="variablelist"><table border="0">
599 <col align="left" valign="top">
600 <tbody><tr>
601 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
602 <td>a newly created <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
603 </td>
604 </tr></tbody>
605 </table></div>
606 <p class="since">Since 2.28</p>
607 </div>
608 <hr>
609 <div class="refsect2">
610 <a name="g-null-settings-backend-new"></a><h3>g_null_settings_backend_new ()</h3>
611 <pre class="programlisting"><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> *  g_null_settings_backend_new         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
612 <p>
613 Creates a readonly <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.
614 </p>
615 <p>
616 This backend does not allow changes to settings, so all settings
617 will always have their default values.
618 </p>
619 <div class="variablelist"><table border="0">
620 <col align="left" valign="top">
621 <tbody><tr>
622 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
623 <td>a newly created <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
624 </td>
625 </tr></tbody>
626 </table></div>
627 <p class="since">Since 2.28</p>
628 </div>
629 </div>
630 <div class="refsect1">
631 <a name="GSettingsBackend.see-also"></a><h2>See Also</h2>
632 <a class="link" href="GSettings.html" title="GSettings"><span class="type">GSettings</span></a>, <a class="link" href="gio-Extension-Points.html#GIOExtensionPoint" title="GIOExtensionPoint"><span class="type">GIOExtensionPoint</span></a>
633 </div>
634 </div>
635 <div class="footer">
636 <hr>
637           Generated by GTK-Doc V1.18</div>
638 </body>
639 </html>