| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>GSettingsBackend: GIO Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GIO Reference Manual"> |
| <link rel="up" href="settings.html" title="Settings"> |
| <link rel="prev" href="GSettings.html" title="GSettings"> |
| <link rel="next" href="gio-GSettingsSchema-GSettingsSchemaSource.html" title="GSettingsSchema, GSettingsSchemaSource"> |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"> |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> |
| <a href="#GSettingsBackend.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> |
| <a href="#GSettingsBackend.object-hierarchy" class="shortcut">Object Hierarchy</a></span> |
| </td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="settings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="GSettings.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="gio-GSettingsSchema-GSettingsSchemaSource.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry"> |
| <a name="GSettingsBackend"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="GSettingsBackend.top_of_page"></a>GSettingsBackend</span></h2> |
| <p>GSettingsBackend — Interface for settings backend implementations</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.functions"></a><h2>Functions</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="functions_return"> |
| <col class="functions_name"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-get-default" title="g_settings_backend_get_default ()">g_settings_backend_get_default</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()">g_settings_backend_changed</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-path-changed" title="g_settings_backend_path_changed ()">g_settings_backend_path_changed</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-keys-changed" title="g_settings_backend_keys_changed ()">g_settings_backend_keys_changed</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-writable-changed" title="g_settings_backend_writable_changed ()">g_settings_backend_writable_changed</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-changed-tree" title="g_settings_backend_changed_tree ()">g_settings_backend_changed_tree</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-flatten-tree" title="g_settings_backend_flatten_tree ()">g_settings_backend_flatten_tree</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-keyfile-settings-backend-new" title="g_keyfile_settings_backend_new ()">g_keyfile_settings_backend_new</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-memory-settings-backend-new" title="g_memory_settings_backend_new ()">g_memory_settings_backend_new</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="returnvalue">GSettingsBackend</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GSettingsBackend.html#g-null-settings-backend-new" title="g_null_settings_backend_new ()">g_null_settings_backend_new</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.other"></a><h2>Types and Values</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="name"> |
| <col class="description"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="datatype_keyword"> </td> |
| <td class="function_name"><a class="link" href="GSettingsBackend.html#GSettingsBackend-struct" title="GSettingsBackend">GSettingsBackend</a></td> |
| </tr> |
| <tr> |
| <td class="datatype_keyword">struct</td> |
| <td class="function_name"><a class="link" href="GSettingsBackend.html#GSettingsBackendClass" title="struct GSettingsBackendClass">GSettingsBackendClass</a></td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"><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></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.object-hierarchy"></a><h2>Object Hierarchy</h2> |
| <pre class="screen"> <a href="../gobject-The-Base-Object-Type.html#GObject-struct">GObject</a> |
| <span class="lineart">╰──</span> GSettingsBackend |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.includes"></a><h2>Includes</h2> |
| <pre class="synopsis">#include <gio/gsettingsbackend.h> |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.description"></a><h2>Description</h2> |
| <p>The <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> interface defines a generic interface for |
| non-strictly-typed data that is stored in a hierarchy. To implement |
| an alternative storage backend for <a class="link" href="GSettings.html" title="GSettings"><span class="type">GSettings</span></a>, you need to implement |
| the <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> interface and then make it implement the |
| 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>.</p> |
| <p>The interface defines methods for reading and writing values, a |
| method for determining if writing of certain values will fail |
| (lockdown) and a change notification mechanism.</p> |
| <p>The semantics of the interface are very precisely defined and |
| implementations must carefully adhere to the expectations of |
| callers that are documented on each of the interface methods.</p> |
| <p>Some of the GSettingsBackend functions accept or return a <a href="../glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a>. |
| These trees always have strings as keys and <a href="../glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> as values. |
| <code class="function">g_settings_backend_create_tree()</code> is a convenience function to create |
| suitable trees.</p> |
| <p>The GSettingsBackend API is exported to allow third-party |
| implementations, but does not carry the same stability guarantees |
| as the public GIO API. For this reason, you have to define the |
| C preprocessor symbol <code class="literal">G_SETTINGS_ENABLE_BACKEND</code> before including |
| <code class="literal">gio/gsettingsbackend.h</code>.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.functions_details"></a><h2>Functions</h2> |
| <div class="refsect2"> |
| <a name="g-settings-backend-get-default"></a><h3>g_settings_backend_get_default ()</h3> |
| <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> |
| <p>Returns the default <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. It is possible to override |
| the default by setting the <code class="literal">GSETTINGS_BACKEND</code> environment variable |
| to the name of a settings backend.</p> |
| <p>The user gets a reference to the backend.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-get-default.returns"></a><h4>Returns</h4> |
| <p> the default <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. </p> |
| <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-28.html#api-index-2.28">2.28</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-changed"></a><h3>g_settings_backend_changed ()</h3> |
| <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>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *key</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre> |
| <p>Signals that a single key has possibly changed. Backend |
| implementations should call this if a key has possibly changed its |
| value.</p> |
| <p><em class="parameter"><code>key</code></em> |
| must be a valid key (ie starting with a slash, not containing |
| '//', and not ending with a slash).</p> |
| <p>The implementation must call this function during any call to |
| <code class="function">g_settings_backend_write()</code>, before the call returns (except in the |
| case that no keys are actually changed and it cares to detect this |
| fact). It may not rely on the existence of a mainloop for |
| dispatching the signal later.</p> |
| <p>The implementation may call this function at any other time it likes |
| in response to other events (such as changes occurring outside of the |
| program). These calls may originate from a mainloop or may originate |
| in response to any other action (including from calls to |
| <code class="function">g_settings_backend_write()</code>).</p> |
| <p>In the case that this call is in response to a call to |
| <code class="function">g_settings_backend_write()</code> then <em class="parameter"><code>origin_tag</code></em> |
| must be set to the same |
| value that was passed to that call.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-changed.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>backend</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>key</p></td> |
| <td class="parameter_description"><p>the name of the key</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>origin_tag</p></td> |
| <td class="parameter_description"><p>the origin tag</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-path-changed"></a><h3>g_settings_backend_path_changed ()</h3> |
| <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>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre> |
| <p>Signals that all keys below a given path may have possibly changed. |
| Backend implementations should call this if an entire path of keys |
| have possibly changed their values.</p> |
| <p><em class="parameter"><code>path</code></em> |
| must be a valid path (ie starting and ending with a slash and |
| not containing '//').</p> |
| <p>The meaning of this signal is that any of the key which has a name |
| starting with <em class="parameter"><code>path</code></em> |
| may have changed.</p> |
| <p>The same rules for when notifications must occur apply as per |
| <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 |
| reasponse to a 'reset' call but implementations are also free to |
| explicitly list the keys that were affected by that call if they can |
| easily do so.</p> |
| <p>For efficiency reasons, the implementation should strive for <em class="parameter"><code>path</code></em> |
| to |
| be as long as possible (ie: the longest common prefix of all of the |
| keys that were changed) but this is not strictly required. As an |
| example, if this function is called with the path of "/" then every |
| single key in the application will be notified of a possible change.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-path-changed.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>backend</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>path</p></td> |
| <td class="parameter_description"><p>the path containing the changes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>origin_tag</p></td> |
| <td class="parameter_description"><p>the origin tag</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-keys-changed"></a><h3>g_settings_backend_keys_changed ()</h3> |
| <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>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> const * const *items</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre> |
| <p>Signals that a list of keys have possibly changed. Backend |
| implementations should call this if keys have possibly changed their |
| values.</p> |
| <p><em class="parameter"><code>path</code></em> |
| must be a valid path (ie starting and ending with a slash and |
| not containing '//'). Each string in <em class="parameter"><code>items</code></em> |
| must form a valid key |
| name when <em class="parameter"><code>path</code></em> |
| is prefixed to it (ie: each item must not start or |
| end with '/' and must not contain '//').</p> |
| <p>The meaning of this signal is that any of the key names resulting |
| from the contatenation of <em class="parameter"><code>path</code></em> |
| with each item in <em class="parameter"><code>items</code></em> |
| may have |
| changed.</p> |
| <p>The same rules for when notifications must occur apply as per |
| <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 |
| interchangeably if exactly one item has changed (although in that |
| 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).</p> |
| <p>For efficiency reasons, the implementation should strive for <em class="parameter"><code>path</code></em> |
| to |
| be as long as possible (ie: the longest common prefix of all of the |
| keys that were changed) but this is not strictly required.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-keys-changed.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>backend</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>path</p></td> |
| <td class="parameter_description"><p>the path containing the changes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>items</p></td> |
| <td class="parameter_description"><p> the <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated list of changed keys. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>origin_tag</p></td> |
| <td class="parameter_description"><p>the origin tag</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-path-writable-changed"></a><h3>g_settings_backend_path_writable_changed ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_settings_backend_path_writable_changed |
| (<em class="parameter"><code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> *backend</code></em>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *path</code></em>);</pre> |
| <p>Signals that the writability of all keys below a given path may have |
| changed.</p> |
| <p>Since GSettings performs no locking operations for itself, this call |
| will always be made in response to external events.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-path-writable-changed.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>backend</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>path</p></td> |
| <td class="parameter_description"><p>the name of the path</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-writable-changed"></a><h3>g_settings_backend_writable_changed ()</h3> |
| <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>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *key</code></em>);</pre> |
| <p>Signals that the writability of a single key has possibly changed.</p> |
| <p>Since GSettings performs no locking operations for itself, this call |
| will always be made in response to external events.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-writable-changed.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>backend</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>key</p></td> |
| <td class="parameter_description"><p>the name of the key</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-changed-tree"></a><h3>g_settings_backend_changed_tree ()</h3> |
| <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>, |
| <em class="parameter"><code><a href="../glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> *tree</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> origin_tag</code></em>);</pre> |
| <p>This call is a convenience wrapper. It gets the list of changes from |
| <em class="parameter"><code>tree</code></em> |
| , computes the longest common prefix and calls |
| <a class="link" href="GSettingsBackend.html#g-settings-backend-changed" title="g_settings_backend_changed ()"><code class="function">g_settings_backend_changed()</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-changed-tree.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>backend</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> implementation</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>tree</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> containing the changes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>origin_tag</p></td> |
| <td class="parameter_description"><p>the origin tag</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-settings-backend-flatten-tree"></a><h3>g_settings_backend_flatten_tree ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_settings_backend_flatten_tree (<em class="parameter"><code><a href="../glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> *tree</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> **path</code></em>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> ***keys</code></em>, |
| <em class="parameter"><code><a href="../glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> ***values</code></em>);</pre> |
| <p>Calculate the longest common prefix of all keys in a tree and write |
| out an array of the key names relative to that prefix and, |
| optionally, the value to store at each of those keys.</p> |
| <p>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 |
| <a href="../glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>. You should not attempt to free or unref the contents of |
| <em class="parameter"><code>keys</code></em> |
| or <em class="parameter"><code>values</code></em> |
| .</p> |
| <div class="refsect3"> |
| <a name="g-settings-backend-flatten-tree.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>tree</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Balanced-Binary-Trees.html#GTree"><span class="type">GTree</span></a> containing the changes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>path</p></td> |
| <td class="parameter_description"><p> the location to save the path. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>keys</p></td> |
| <td class="parameter_description"><p> the |
| location to save the relative keys. </p></td> |
| <td class="parameter_annotations"><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></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>values</p></td> |
| <td class="parameter_description"><p> the location to save the values, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> |
| <td class="parameter_annotations"><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></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-26.html#api-index-2.26">2.26</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-keyfile-settings-backend-new"></a><h3>g_keyfile_settings_backend_new ()</h3> |
| <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-Basic-Types.html#gchar"><span class="type">gchar</span></a> *filename</code></em>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *root_path</code></em>, |
| <em class="parameter"><code>const <a href="../glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *root_group</code></em>);</pre> |
| <p>Creates a keyfile-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.</p> |
| <p>The filename of the keyfile to use is given by <em class="parameter"><code>filename</code></em> |
| .</p> |
| <p>All settings read to or written from the backend must fall under the |
| path given in <em class="parameter"><code>root_path</code></em> |
| (which must start and end with a slash and |
| not contain two consecutive slashes). <em class="parameter"><code>root_path</code></em> |
| may be "/".</p> |
| <p>If <em class="parameter"><code>root_group</code></em> |
| is non-<a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it specifies the name of the keyfile |
| group used for keys that are written directly below <em class="parameter"><code>root_path</code></em> |
| . For |
| example, if <em class="parameter"><code>root_path</code></em> |
| is "/apps/example/" and <em class="parameter"><code>root_group</code></em> |
| is |
| "toplevel", then settings the key "/apps/example/enabled" to a value |
| of <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> will cause the following to appear in the keyfile:</p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="symbol">[</span><span class="normal">toplevel</span><span class="symbol">]</span> |
| <span class="normal">enabled</span><span class="symbol">=</span><span class="normal">true</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p></p> |
| <p>If <em class="parameter"><code>root_group</code></em> |
| is <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it is not permitted to store keys |
| directly below the <em class="parameter"><code>root_path</code></em> |
| .</p> |
| <p>For keys not stored directly below <em class="parameter"><code>root_path</code></em> |
| (ie: in a sub-path), |
| the name of the subpath (with the final slash stripped) is used as |
| the name of the keyfile group. To continue the example, if |
| "/apps/example/profiles/default/font-size" were set to |
| 12 then the following would appear in the keyfile:</p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="symbol">[</span><span class="normal">profiles</span><span class="symbol">/</span><span class="keyword">default</span><span class="symbol">]</span> |
| <span class="normal">font</span><span class="symbol">-</span><span class="normal">size</span><span class="symbol">=</span><span class="number">12</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p></p> |
| <p>The backend will refuse writes (and return writability as being |
| <a href="../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 |
| <em class="parameter"><code>root_group</code></em> |
| is <a href="../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> |
| . |
| Writes will also be refused if the backend detects that it has the |
| inability to rewrite the keyfile (ie: the containing directory is not |
| writable).</p> |
| <p>There is no checking done for your key namespace clashing with the |
| syntax of the key file format. For example, if you have '[' or ']' |
| characters in your path names or '=' in your key names you may be in |
| trouble.</p> |
| <div class="refsect3"> |
| <a name="g-keyfile-settings-backend-new.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>filename</p></td> |
| <td class="parameter_description"><p>the filename of the keyfile</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>root_path</p></td> |
| <td class="parameter_description"><p>the path under which all settings keys appear</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>root_group</p></td> |
| <td class="parameter_description"><p> the group name corresponding to |
| <em class="parameter"><code>root_path</code></em> |
| , or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-keyfile-settings-backend-new.returns"></a><h4>Returns</h4> |
| <p> a keyfile-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. </p> |
| <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-memory-settings-backend-new"></a><h3>g_memory_settings_backend_new ()</h3> |
| <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> |
| <p>Creates a memory-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.</p> |
| <p>This backend allows changes to settings, but does not write them |
| to any backing storage, so the next time you run your application, |
| the memory backend will start out with the default values again.</p> |
| <div class="refsect3"> |
| <a name="g-memory-settings-backend-new.returns"></a><h4>Returns</h4> |
| <p> a newly created <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. </p> |
| <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-28.html#api-index-2.28">2.28</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-null-settings-backend-new"></a><h3>g_null_settings_backend_new ()</h3> |
| <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> |
| <p>Creates a readonly <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.</p> |
| <p>This backend does not allow changes to settings, so all settings |
| will always have their default values.</p> |
| <div class="refsect3"> |
| <a name="g-null-settings-backend-new.returns"></a><h4>Returns</h4> |
| <p> a newly created <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>. </p> |
| <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-28.html#api-index-2.28">2.28</a></p> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.other_details"></a><h2>Types and Values</h2> |
| <div class="refsect2"> |
| <a name="GSettingsBackend-struct"></a><h3>GSettingsBackend</h3> |
| <pre class="programlisting">typedef struct _GSettingsBackend GSettingsBackend;</pre> |
| <p>An implementation of a settings storage repository.</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GSettingsBackendClass"></a><h3>struct GSettingsBackendClass</h3> |
| <pre class="programlisting">struct GSettingsBackendClass { |
| GObjectClass parent_class; |
| |
| GVariant * (*read) (GSettingsBackend *backend, |
| const gchar *key, |
| const GVariantType *expected_type, |
| gboolean default_value); |
| |
| gboolean (*get_writable) (GSettingsBackend *backend, |
| const gchar *key); |
| |
| gboolean (*write) (GSettingsBackend *backend, |
| const gchar *key, |
| GVariant *value, |
| gpointer origin_tag); |
| gboolean (*write_tree) (GSettingsBackend *backend, |
| GTree *tree, |
| gpointer origin_tag); |
| void (*reset) (GSettingsBackend *backend, |
| const gchar *key, |
| gpointer origin_tag); |
| |
| void (*subscribe) (GSettingsBackend *backend, |
| const gchar *name); |
| void (*unsubscribe) (GSettingsBackend *backend, |
| const gchar *name); |
| void (*sync) (GSettingsBackend *backend); |
| |
| GPermission * (*get_permission) (GSettingsBackend *backend, |
| const gchar *path); |
| |
| GVariant * (*read_user_value) (GSettingsBackend *backend, |
| const gchar *key, |
| const GVariantType *expected_type); |
| }; |
| </pre> |
| <p>Class structure for <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a>.</p> |
| <div class="refsect3"> |
| <a name="GSettingsBackendClass.members"></a><h4>Members</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="300px" class="struct_members_name"> |
| <col class="struct_members_description"> |
| <col width="200px" class="struct_members_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.read"></a>read</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to read a key's value</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.get-writable"></a>get_writable</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to get if a key is writable</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.write"></a>write</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to change key's value</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.write-tree"></a>write_tree</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to change a tree of keys</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.reset"></a>reset</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to reset state</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.subscribe"></a>subscribe</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to subscribe to key changes</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.unsubscribe"></a>unsubscribe</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to unsubscribe to key changes</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.sync"></a>sync</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to sync state</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.get-permission"></a>get_permission</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to get permission of a key</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><em class="structfield"><code><a name="GSettingsBackendClass.read-user-value"></a>read_user_value</code></em> ()</p></td> |
| <td class="struct_member_description"><p>virtual method to read user's key value</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="G-SETTINGS-BACKEND-EXTENSION-POINT-NAME:CAPS"></a><h3>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</h3> |
| <pre class="programlisting">#define G_SETTINGS_BACKEND_EXTENSION_POINT_NAME "gsettings-backend" |
| </pre> |
| <p>Extension point for <a class="link" href="GSettingsBackend.html" title="GSettingsBackend"><span class="type">GSettingsBackend</span></a> functionality.</p> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="GSettingsBackend.see-also"></a><h2>See Also</h2> |
| <p><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></p> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25.1</div> |
| </body> |
| </html> |
