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>