|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /proc/22697/root/usr/share/gtk-doc/html/gconf/ |
Upload File : |
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>GConfClient</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
<link rel="start" href="index.html" title="GConf Reference Manual">
<link rel="up" href="ch01.html" title="Using the GConf library">
<link rel="prev" href="ch01.html" title="Using the GConf library">
<link rel="next" href="gconf-gconf-backend.html" title="gconf-backend">
<meta name="generator" content="GTK-Doc V1.4 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="ch01.html" title="Using the GConf library">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="ch01.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GConf Reference Manual</th>
<td><a accesskey="n" href="gconf-gconf-backend.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry" lang="en">
<a name="gconf-GConfClient"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">GConfClient</span></h2>
<p>GConfClient —
<span class="type">GObject-based</span> convenience wrapper</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<pre class="synopsis">
enum <a href="gconf-GConfClient.html#GConfClientPreloadType">GConfClientPreloadType</a>;
enum <a href="gconf-GConfClient.html#GConfClientErrorHandlingMode">GConfClientErrorHandlingMode</a>;
void (<a href="gconf-GConfClient.html#GConfClientNotifyFunc">*GConfClientNotifyFunc</a>) (GConfClient *client,
guint cnxn_id,
<a href="gconf-gconf-value.html#GConfEntry">GConfEntry</a> *entry,
gpointer user_data);
void (<a href="gconf-GConfClient.html#GConfClientErrorHandlerFunc">*GConfClientErrorHandlerFunc</a>) (GConfClient *client,
GError *error);
#define <a href="gconf-GConfClient.html#GCONF-CLIENT:CAPS">GCONF_CLIENT</a> (obj)
GConfClient* <a href="gconf-GConfClient.html#gconf-client-get-default">gconf_client_get_default</a> (void);
GConfClient* <a href="gconf-GConfClient.html#gconf-client-get-for-engine">gconf_client_get_for_engine</a> (<a href="gconf-gconf-engine.html#GConfEngine">GConfEngine</a> *engine);
void <a href="gconf-GConfClient.html#gconf-client-add-dir">gconf_client_add_dir</a> (GConfClient *client,
const gchar *dir,
<a href="gconf-GConfClient.html#GConfClientPreloadType">GConfClientPreloadType</a> preload,
GError **err);
void <a href="gconf-GConfClient.html#gconf-client-remove-dir">gconf_client_remove_dir</a> (GConfClient *client,
const gchar *dir,
GError **err);
guint <a href="gconf-GConfClient.html#gconf-client-notify-add">gconf_client_notify_add</a> (GConfClient *client,
const gchar *namespace_section,
<a href="gconf-GConfClient.html#GConfClientNotifyFunc">GConfClientNotifyFunc</a> func,
gpointer user_data,
GFreeFunc destroy_notify,
GError **err);
void <a href="gconf-GConfClient.html#gconf-client-notify-remove">gconf_client_notify_remove</a> (GConfClient *client,
guint cnxn);
void <a href="gconf-GConfClient.html#gconf-client-notify">gconf_client_notify</a> (GConfClient *client,
const char *key);
void <a href="gconf-GConfClient.html#gconf-client-set-error-handling">gconf_client_set_error_handling</a> (GConfClient *client,
<a href="gconf-GConfClient.html#GConfClientErrorHandlingMode">GConfClientErrorHandlingMode</a> mode);
void <a href="gconf-GConfClient.html#gconf-client-set-global-default-error-handler">gconf_client_set_global_default_error_handler</a>
(<a href="gconf-GConfClient.html#GConfClientErrorHandlerFunc">GConfClientErrorHandlerFunc</a> func);
void <a href="gconf-GConfClient.html#gconf-client-clear-cache">gconf_client_clear_cache</a> (GConfClient *client);
void <a href="gconf-GConfClient.html#gconf-client-preload">gconf_client_preload</a> (GConfClient *client,
const gchar *dirname,
<a href="gconf-GConfClient.html#GConfClientPreloadType">GConfClientPreloadType</a> type,
GError **err);
void <a href="gconf-GConfClient.html#gconf-client-set">gconf_client_set</a> (GConfClient *client,
const gchar *key,
const <a href="gconf-gconf-value.html#GConfValue">GConfValue</a> *val,
GError **err);
<a href="gconf-gconf-value.html#GConfValue">GConfValue</a>* <a href="gconf-GConfClient.html#gconf-client-get">gconf_client_get</a> (GConfClient *client,
const gchar *key,
GError **err);
<a href="gconf-gconf-value.html#GConfValue">GConfValue</a>* <a href="gconf-GConfClient.html#gconf-client-get-without-default">gconf_client_get_without_default</a>
(GConfClient *client,
const gchar *key,
GError **err);
<a href="gconf-gconf-value.html#GConfEntry">GConfEntry</a>* <a href="gconf-GConfClient.html#gconf-client-get-entry">gconf_client_get_entry</a> (GConfClient *client,
const gchar *key,
const gchar *locale,
gboolean use_schema_default,
GError **err);
<a href="gconf-gconf-value.html#GConfValue">GConfValue</a>* <a href="gconf-GConfClient.html#gconf-client-get-default-from-schema">gconf_client_get_default_from_schema</a>
(GConfClient *client,
const gchar *key,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-unset">gconf_client_unset</a> (GConfClient *client,
const gchar *key,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-recursive-unset">gconf_client_recursive_unset</a> (GConfClient *client,
const char *key,
GConfUnsetFlags flags,
GError **err);
GSList* <a href="gconf-GConfClient.html#gconf-client-all-entries">gconf_client_all_entries</a> (GConfClient *client,
const gchar *dir,
GError **err);
GSList* <a href="gconf-GConfClient.html#gconf-client-all-dirs">gconf_client_all_dirs</a> (GConfClient *client,
const gchar *dir,
GError **err);
void <a href="gconf-GConfClient.html#gconf-client-suggest-sync">gconf_client_suggest_sync</a> (GConfClient *client,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-dir-exists">gconf_client_dir_exists</a> (GConfClient *client,
const gchar *dir,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-key-is-writable">gconf_client_key_is_writable</a> (GConfClient *client,
const gchar *key,
GError **err);
gdouble <a href="gconf-GConfClient.html#gconf-client-get-float">gconf_client_get_float</a> (GConfClient *client,
const gchar *key,
GError **err);
gint <a href="gconf-GConfClient.html#gconf-client-get-int">gconf_client_get_int</a> (GConfClient *client,
const gchar *key,
GError **err);
gchar* <a href="gconf-GConfClient.html#gconf-client-get-string">gconf_client_get_string</a> (GConfClient *client,
const gchar *key,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-get-bool">gconf_client_get_bool</a> (GConfClient *client,
const gchar *key,
GError **err);
<a href="gconf-gconf-schema.html#GConfSchema">GConfSchema</a>* <a href="gconf-GConfClient.html#gconf-client-get-schema">gconf_client_get_schema</a> (GConfClient *client,
const gchar *key,
GError **err);
GSList* <a href="gconf-GConfClient.html#gconf-client-get-list">gconf_client_get_list</a> (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> list_type,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-get-pair">gconf_client_get_pair</a> (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> car_type,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> cdr_type,
gpointer car_retloc,
gpointer cdr_retloc,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-float">gconf_client_set_float</a> (GConfClient *client,
const gchar *key,
gdouble val,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-int">gconf_client_set_int</a> (GConfClient *client,
const gchar *key,
gint val,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-string">gconf_client_set_string</a> (GConfClient *client,
const gchar *key,
const gchar *val,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-bool">gconf_client_set_bool</a> (GConfClient *client,
const gchar *key,
gboolean val,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-schema">gconf_client_set_schema</a> (GConfClient *client,
const gchar *key,
const <a href="gconf-gconf-schema.html#GConfSchema">GConfSchema</a> *val,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-list">gconf_client_set_list</a> (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> list_type,
GSList *list,
GError **err);
gboolean <a href="gconf-GConfClient.html#gconf-client-set-pair">gconf_client_set_pair</a> (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> car_type,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> cdr_type,
gconstpointer address_of_car,
gconstpointer address_of_cdr,
GError **err);
void <a href="gconf-GConfClient.html#gconf-client-error">gconf_client_error</a> (GConfClient *client,
GError *error);
void <a href="gconf-GConfClient.html#gconf-client-unreturned-error">gconf_client_unreturned_error</a> (GConfClient *client,
GError *error);
void <a href="gconf-GConfClient.html#gconf-client-value-changed">gconf_client_value_changed</a> (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValue">GConfValue</a> *value);
gboolean <a href="gconf-GConfClient.html#gconf-client-commit-change-set">gconf_client_commit_change_set</a> (GConfClient *client,
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a> *cs,
gboolean remove_committed,
GError **err);
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a>* <a href="gconf-GConfClient.html#gconf-client-reverse-change-set">gconf_client_reverse_change_set</a>
(GConfClient *client,
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a> *cs,
GError **err);
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a>* <a href="gconf-GConfClient.html#gconf-client-change-set-from-currentv">gconf_client_change_set_from_currentv</a>
(GConfClient *client,
const gchar **keys,
GError **err);
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a>* <a href="gconf-GConfClient.html#gconf-client-change-set-from-current">gconf_client_change_set_from_current</a>
(GConfClient *client,
GError **err,
const gchar *first_key,
...);
</pre>
</div>
<div class="refsect1" lang="en">
<a name="id2568048"></a><h2>Description</h2>
<p>
<span class="type">GConfClient</span> adds the following features to plain GConf:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
A client-side cache for a specified list of directories you're interested in.
You can "preload" entire directories into the cache, speeding things up even more.
</p></li>
<li><p>
Some automatic error handling, if you request it.
</p></li>
<li><p>
Signals when a value changes or an error occurs.
</p></li>
</ul></div>
<p>
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>
If you use <span class="type">GConfClient</span>, you should not use the underlying <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a>
directly, or you'll break things. This is why there's no
<code class="function">gconf_client_get_engine()</code> function; in fact, if you create the <span class="type">GConfClient</span> with
<a href="gconf-GConfClient.html#gconf-client-get-default"><code class="function">gconf_client_get_default()</code></a>, there is no (legitimate) way to obtain a pointer to the
underlying <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a>. If you create a <span class="type">GConfClient</span> from an existing engine,
you'll have to be disciplined enough to avoid using that engine directly.
<sup>[<a name="id2568148" href="#ftn.id2568148">1</a>]</sup>
</p>
</div>
<p>
A <span class="type">GConfClient</span> has a list of directories that it "watches." These directories
are optionally pre-loaded into the cache, and monitored in order to emit the
<span class="type">value_changed</span> signal. The <span class="type">GConfClient</span> can also be used to access directories
not in the list, but those directories won't be preloaded and the "value_changed"
signal won't be emitted for them.
</p>
<p>
There are two error-related signals in <span class="type">GConfClient</span>. The first is plain "error";
it's emitted anytime an error occurs. The second is "unreturned_error"; this
signal is emitted if you pass <span class="symbol">NULL</span> as the <span class="type">GError</span>** to any
<span class="type">GConfClient</span> function. The idea is that you can have a global error handler
attached to the "unreturned_error" signal; if you want to use this handler, you
don't need to use the normal GConf error handling mechanism. However, if you
ever need to handle errors for a specific function call, you can override the
global handler by passing a non-<span class="symbol">NULL</span> <span class="type">GError</span>** to the
function. If you want an error handler that's <span class="emphasis"><em>always</em></span>
invoked, use the "error" signal.
</p>
<p>
The "value_changed" signal is emitted whenever the server notifies your client
program that a value has changed in the GConf database. There's one problem with
this signal: the signal handler has to use <code class="function">strcmp()</code> to determine whether the
changed value is the one it was interested in. If you are interested in lots of
values, then every time a value changes you'll be making lots of calls to
<code class="function">strcmp()</code> and getting O(n) performance. <a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a> is a superior
interface in most cases for this reason. Note that calling <a href="gconf-GConfClient.html#gconf-client-set"><code class="function">gconf_client_set()</code></a>
and its relatives will cause "value_changed" to be emitted, but "value_changed"
is also emitted if another process changes the value.
</p>
<p>
Most of the <span class="type">GConfClient</span> interface mirrors the functions you'd use to manipulate
a <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a> (<a href="gconf-gconf.html#gconf-engine-get"><code class="function">gconf_engine_get()</code></a> and <a href="gconf-GConfClient.html#gconf-client-get"><code class="function">gconf_client_get()</code></a>, for example). These should
all work just like the <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a> versions, except that they use the cache
from <span class="type">GConfClient</span> and emit the <span class="type">GConfClient</span> signals.
</p>
<p>
As always with GConf, applications based on <span class="type">GConfClient</span> should use a
model-controller-view architecture. Typically, this means that areas of your
application affected by a setting will monitor the relevant key and update
themselves when necessary. The preferences dialog will simply change keys,
allowing GConf to notify the rest of the application that changes have occurred.
Here the application proper is the "view," GConf is the "model", and the
preferences dialog is the "controller." In no case should you do this:
</p>
<pre class="programlisting">
gconf_client_set(client, key, value);
<code class="function">application_update_to_reflect_setting()</code>;
</pre>
<p>
This breaks if a setting is changed <span class="emphasis"><em>outside</em></span> your
application—or even from a different part of your application.
The correct way (in pseudo-code) is:
</p>
<pre class="programlisting">
/* At application startup */
gconf_client_notify_add(client, key, application_update_to_reflect_setting, data);
/* From preferences dialog */
gconf_client_set(client, key, value);
</pre>
<p>
See the example programs that come with GConf for more details.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2568399"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id2568404"></a><h3>
<a name="GConfClientPreloadType"></a>enum GConfClientPreloadType</h3>
<a class="indexterm" name="id2568412"></a><pre class="programlisting">typedef enum { /*< prefix=GCONF_CLIENT >*/
GCONF_CLIENT_PRELOAD_NONE, /* don't preload anything */
GCONF_CLIENT_PRELOAD_ONELEVEL, /* load entries directly under the directory. */
GCONF_CLIENT_PRELOAD_RECURSIVE /* recurse the directory tree; possibly quite expensive! */
} GConfClientPreloadType;
</pre>
<p>
The <a href="gconf-GConfClient.html#GConfClientPreloadType"><span class="type">GConfClientPreloadType</span></a> is used to tell <span class="type">GConfClient</span> how to preload one of
its directories. As a rule of thumb, if you plan to get the value of almost all the
keys in a directory, preloading that directory will probably enhance
performance. If you plan to use only half the keys, preloading is likely a bad
idea. <em class="parameter"><code>GCONF_CLIENT_PRELOAD_NONE</code></em> specifies that no preload occurs,
<em class="parameter"><code>GCONF_CLIENT_PRELOAD_ONELEVEL</code></em> loads the immediate children of the directory,
<em class="parameter"><code>GCONF_CLIENT_PRELOAD_RECURSIVE</code></em> loads <span class="emphasis"><em>all</em></span> children of the
directory and its subdirectories, recursively.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><code class="literal">GCONF_CLIENT_PRELOAD_NONE</code></span></td>
<td>preload nothing.
</td>
</tr>
<tr>
<td>
<span class="term"><code class="literal">GCONF_CLIENT_PRELOAD_ONELEVEL</code></span></td>
<td>preload immediate children of the directory.
</td>
</tr>
<tr>
<td>
<span class="term"><code class="literal">GCONF_CLIENT_PRELOAD_RECURSIVE</code></span></td>
<td>recursively preload everything in and below the directory.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2568520"></a><h3>
<a name="GConfClientErrorHandlingMode"></a>enum GConfClientErrorHandlingMode</h3>
<a class="indexterm" name="id2568530"></a><pre class="programlisting">typedef enum { /*< prefix=GCONF_CLIENT >*/
GCONF_CLIENT_HANDLE_NONE,
GCONF_CLIENT_HANDLE_UNRETURNED,
GCONF_CLIENT_HANDLE_ALL
} GConfClientErrorHandlingMode;
</pre>
<p>
<a href="gconf-GConfClient.html#GConfClientErrorHandlingMode"><span class="type">GConfClientErrorHandlingMode</span></a> is used to control <span class="type">GConfClient</span>'s default error
handling. <span class="type">GConfClient</span> can pop up a dialog in the default signal handler for
"error" or "unreturned_error." You can specify that no errors are handled, only
unreturned errors are handled, or all errors are handled with this enumeration.
You can prevent specific errors from being handled automatically by stopping the
signal emission before the default signal handler is called (see the GLib
documentation, <code class="function">g_signal_stop_emission_by_name()</code> for example).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><code class="literal">GCONF_CLIENT_HANDLE_NONE</code></span></td>
<td>never run a default error handler.
</td>
</tr>
<tr>
<td>
<span class="term"><code class="literal">GCONF_CLIENT_HANDLE_UNRETURNED</code></span></td>
<td>run a default error handler for unreturned errors ("unreturned_error" signal).
</td>
</tr>
<tr>
<td>
<span class="term"><code class="literal">GCONF_CLIENT_HANDLE_ALL</code></span></td>
<td>run a default error handler for all errors ("error" signal).
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2568634"></a><h3>
<a name="GConfClientNotifyFunc"></a>GConfClientNotifyFunc ()</h3>
<a class="indexterm" name="id2568642"></a><pre class="programlisting">void (*GConfClientNotifyFunc) (GConfClient *client,
guint cnxn_id,
<a href="gconf-gconf-value.html#GConfEntry">GConfEntry</a> *entry,
gpointer user_data);</pre>
<p>
This is the signature of a user function added with <a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a>.
The notify function is invoked when the value of a key changes. The <em class="parameter"><code>value</code></em>
argument is the new value, or <span class="symbol">NULL</span> if the key was unset. The
<em class="parameter"><code>value</code></em> argument should not be modified, and should be copied if you want to keep
it around (the <span class="type">GConfClient</span> will destroy it sometime after your notify function
is called).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>the <span class="type">GConfClient</span> notifying us.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cnxn_id</code></em> :</span></td>
<td>connection ID from <a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>entry</code></em> :</span></td>
<td>a <a href="gconf-gconf-value.html#GConfEntry"><span class="type">GConfEntry</span></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>user_data</code></em> :</span></td>
<td>user data from <a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2568803"></a><h3>
<a name="GConfClientErrorHandlerFunc"></a>GConfClientErrorHandlerFunc ()</h3>
<a class="indexterm" name="id2568812"></a><pre class="programlisting">void (*GConfClientErrorHandlerFunc) (GConfClient *client,
GError *error);</pre>
<p>
This is the signature of a user function which needs to be called for error
handling.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>error</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2568890"></a><h3>
<a name="GCONF-CLIENT:CAPS"></a>GCONF_CLIENT()</h3>
<a class="indexterm" name="id2568898"></a><pre class="programlisting">#define GCONF_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GCONF_TYPE_CLIENT, GConfClient))
</pre>
<p>
Casts a pointer to a <span class="type">GConfClient</span>*.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>obj</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2568943"></a><h3>
<a name="gconf-client-get-default"></a>gconf_client_get_default ()</h3>
<a class="indexterm" name="id2568952"></a><pre class="programlisting">GConfClient* gconf_client_get_default (void);</pre>
<p>
Creates a new <span class="type">GConfClient</span> using the default <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a>. Normally this is the
engine you want. If someone else is already using the default
<span class="type">GConfClient</span>, this function returns the same one they're using, but
with the reference count incremented. So you have to unref either way.
</p>
<p>
It's important to call <code class="function">g_type_init()</code> before using this GObject, to initialize the type system.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a new <span class="type">GConfClient</span>. <code class="function">g_object_unref()</code> when you're done.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569034"></a><h3>
<a name="gconf-client-get-for-engine"></a>gconf_client_get_for_engine ()</h3>
<a class="indexterm" name="id2569043"></a><pre class="programlisting">GConfClient* gconf_client_get_for_engine (<a href="gconf-gconf-engine.html#GConfEngine">GConfEngine</a> *engine);</pre>
<p>
Creates a new <span class="type">GConfClient</span> with a specific <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a>. Only specialized
configuration-related programs should need to call this function. The
returned <span class="type">GConfClient</span> should be unref'd when you're done with <code class="function">g_object_unref()</code>.
Remember to avoid using the <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a> directly once you have a <span class="type">GConfClient</span>
wrapper.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>engine</code></em> :</span></td>
<td>the <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a> to use.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a new <span class="type">GConfClient</span>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569148"></a><h3>
<a name="gconf-client-add-dir"></a>gconf_client_add_dir ()</h3>
<a class="indexterm" name="id2569156"></a><pre class="programlisting">void gconf_client_add_dir (GConfClient *client,
const gchar *dir,
<a href="gconf-GConfClient.html#GConfClientPreloadType">GConfClientPreloadType</a> preload,
GError **err);</pre>
<p>
Add a directory to the list of directories the <span class="type">GConfClient</span> will watch. Any
changes to keys below this directory will cause the "value_changed" signal to be
emitted. When you add the directory, you can request that the <span class="type">GConfClient</span>
preload its contents; see <a href="gconf-GConfClient.html#GConfClientPreloadType"><span class="type">GConfClientPreloadType</span></a> for details.
</p>
<p>
Added directories may not overlap. That is, if you add "/foo", you may not add
"/foo/bar". However you can add "/foo" and "/bar". You can also add "/foo"
multiple times; if you add a directory multiple times, it will not be removed
until you call <a href="gconf-GConfClient.html#gconf-client-remove-dir"><code class="function">gconf_client_remove_dir()</code></a> an equal number of times.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dir</code></em> :</span></td>
<td>directory to add to the list.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>preload</code></em> :</span></td>
<td>degree of preload.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569309"></a><h3>
<a name="gconf-client-remove-dir"></a>gconf_client_remove_dir ()</h3>
<a class="indexterm" name="id2569318"></a><pre class="programlisting">void gconf_client_remove_dir (GConfClient *client,
const gchar *dir,
GError **err);</pre>
<p>
Remove a directory from the list created with <a href="gconf-GConfClient.html#gconf-client-add-dir"><code class="function">gconf_client_add_dir()</code></a>. If any
notifications have been added below this directory with
<a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a>, those notifications will be disabled until you re-add
the removed directory. Note that if a directory has been added multiple times,
you must remove it the same number of times before the remove takes effect.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dir</code></em> :</span></td>
<td>directory to remove.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569435"></a><h3>
<a name="gconf-client-notify-add"></a>gconf_client_notify_add ()</h3>
<a class="indexterm" name="id2569444"></a><pre class="programlisting">guint gconf_client_notify_add (GConfClient *client,
const gchar *namespace_section,
<a href="gconf-GConfClient.html#GConfClientNotifyFunc">GConfClientNotifyFunc</a> func,
gpointer user_data,
GFreeFunc destroy_notify,
GError **err);</pre>
<p>
Request notification of changes to <em class="parameter"><code>namespace_section</code></em>. This includes the key
<em class="parameter"><code>namespace_section</code></em> itself, and any keys below it (the behavior is identical to
<a href="gconf-gconf.html#gconf-engine-notify-add"><code class="function">gconf_engine_notify_add()</code></a>, but while <a href="gconf-gconf.html#gconf-engine-notify-add"><code class="function">gconf_engine_notify_add()</code></a> places a notification request
on the server for every notify function, <span class="type">GConfClient</span> requests server
notification for directories added with <a href="gconf-GConfClient.html#gconf-client-add-dir"><code class="function">gconf_client_add_dir()</code></a> and keeps the
list of <a href="gconf-GConfClient.html#GConfClientNotifyFunc"><span class="type">GConfClientNotifyFunc</span></a> on the client side).
</p>
<p>
For the notification to happen, <em class="parameter"><code>namespace_section</code></em> must be equal to or below one
of the directories added with <a href="gconf-GConfClient.html#gconf-client-add-dir"><code class="function">gconf_client_add_dir()</code></a>. You can still call
<a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a> for other directories, but no notification will be
received until you add a directory above or equal to <em class="parameter"><code>namespace_section</code></em>. One
implication of this is that <a href="gconf-GConfClient.html#gconf-client-remove-dir"><code class="function">gconf_client_remove_dir()</code></a> temporarily disables
notifications that were below the removed directory.
</p>
<p>
The function returns a connection ID you can use to call
<a href="gconf-GConfClient.html#gconf-client-notify-remove"><code class="function">gconf_client_notify_remove()</code></a>.
</p>
<p>
See the description of <a href="gconf-GConfClient.html#GConfClientNotifyFunc"><span class="type">GConfClientNotifyFunc</span></a> for details on how the
notification function is called.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>namespace_section</code></em> :</span></td>
<td>where to listen for changes.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>func</code></em> :</span></td>
<td>function to call when changes occur.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>user_data</code></em> :</span></td>
<td>user data to pass to <em class="parameter"><code>func</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>destroy_notify</code></em> :</span></td>
<td>function to call on <em class="parameter"><code>user_data</code></em> when the notify is removed or the <span class="type">GConfClient</span> is destroyed, or <span class="symbol">NULL</span> for none.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a connection ID for removing the notification.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569748"></a><h3>
<a name="gconf-client-notify-remove"></a>gconf_client_notify_remove ()</h3>
<a class="indexterm" name="id2569757"></a><pre class="programlisting">void gconf_client_notify_remove (GConfClient *client,
guint cnxn);</pre>
<p>
Remove a notification using the ID returned from
<a href="gconf-GConfClient.html#gconf-client-notify-add"><code class="function">gconf_client_notify_add()</code></a>. Invokes the destroy notify function on the
notification's user data, if appropriate.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cnxn</code></em> :</span></td>
<td>connection ID.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569834"></a><h3>
<a name="gconf-client-notify"></a>gconf_client_notify ()</h3>
<a class="indexterm" name="id2569842"></a><pre class="programlisting">void gconf_client_notify (GConfClient *client,
const char *key);</pre>
<p>
Emits the "value-changed" signal and notifies listeners as if <em class="parameter"><code>key</code></em> had been
changed
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>the key that has changed.
</td>
</tr>
</tbody>
</table></div>
<p>Since 2.4.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2569919"></a><h3>
<a name="gconf-client-set-error-handling"></a>gconf_client_set_error_handling ()</h3>
<a class="indexterm" name="id2569929"></a><pre class="programlisting">void gconf_client_set_error_handling (GConfClient *client,
<a href="gconf-GConfClient.html#GConfClientErrorHandlingMode">GConfClientErrorHandlingMode</a> mode);</pre>
<p>
Controls the default error handling for <span class="type">GConfClient</span>. See
<a href="gconf-GConfClient.html#GConfClientErrorHandlingMode"><span class="type">GConfClientErrorHandlingMode</span></a> and <span class="type">GConfClientParentWindowFunc</span> for details on this.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>mode</code></em> :</span></td>
<td>error handling mode.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570018"></a><h3>
<a name="gconf-client-set-global-default-error-handler"></a>gconf_client_set_global_default_error_handler ()</h3>
<a class="indexterm" name="id2570029"></a><pre class="programlisting">void gconf_client_set_global_default_error_handler
(<a href="gconf-GConfClient.html#GConfClientErrorHandlerFunc">GConfClientErrorHandlerFunc</a> func);</pre>
<p>
Set <em class="parameter"><code>func</code></em> as the default error handler for the <span class="type">GConfClient</span>. This handler would be called
for all <span class="type">GConfClient</span> internal errors.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>func</code></em> :</span></td>
<td>pointer to the function to be called for error handling.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570092"></a><h3>
<a name="gconf-client-clear-cache"></a>gconf_client_clear_cache ()</h3>
<a class="indexterm" name="id2570100"></a><pre class="programlisting">void gconf_client_clear_cache (GConfClient *client);</pre>
<p>
Dumps everything out of the <span class="type">GConfClient</span> client-side cache. If you know you're
done using the <span class="type">GConfClient</span> for a while, you can call this function to save some
memory.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570162"></a><h3>
<a name="gconf-client-preload"></a>gconf_client_preload ()</h3>
<a class="indexterm" name="id2570171"></a><pre class="programlisting">void gconf_client_preload (GConfClient *client,
const gchar *dirname,
<a href="gconf-GConfClient.html#GConfClientPreloadType">GConfClientPreloadType</a> type,
GError **err);</pre>
<p>
Preloads a directory. Normally you do this when you call <a href="gconf-GConfClient.html#gconf-client-add-dir"><code class="function">gconf_client_add_dir()</code></a>,
but if you've called <a href="gconf-GConfClient.html#gconf-client-clear-cache"><code class="function">gconf_client_clear_cache()</code></a> there may be a reason to do it
again.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dirname</code></em> :</span></td>
<td>directory to preload.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>type</code></em> :</span></td>
<td>degree of preload.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570303"></a><h3>
<a name="gconf-client-set"></a>gconf_client_set ()</h3>
<a class="indexterm" name="id2570312"></a><pre class="programlisting">void gconf_client_set (GConfClient *client,
const gchar *key,
const <a href="gconf-gconf-value.html#GConfValue">GConfValue</a> *val,
GError **err);</pre>
<p>
Sets the value of a configuration key. Just like <a href="gconf-gconf.html#gconf-engine-set"><code class="function">gconf_engine_set()</code></a>, but uses
<span class="type">GConfClient</span> caching and error-handling features. The <em class="parameter"><code>val</code></em> argument will not be
modified.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key to set.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>val</code></em> :</span></td>
<td>new value.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570450"></a><h3>
<a name="gconf-client-get"></a>gconf_client_get ()</h3>
<a class="indexterm" name="id2570460"></a><pre class="programlisting"><a href="gconf-gconf-value.html#GConfValue">GConfValue</a>* gconf_client_get (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Gets the value of a configuration key. Just like <a href="gconf-gconf.html#gconf-engine-get"><code class="function">gconf_engine_get()</code></a>, but uses
<span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key to get.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>newly-allocated <a href="gconf-gconf-value.html#GConfValue"><span class="type">GConfValue</span></a>, or <span class="symbol">NULL</span> if unset and no default exists.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570607"></a><h3>
<a name="gconf-client-get-without-default"></a>gconf_client_get_without_default ()</h3>
<a class="indexterm" name="id2570618"></a><pre class="programlisting"><a href="gconf-gconf-value.html#GConfValue">GConfValue</a>* gconf_client_get_without_default
(GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Gets the value of a configuration key. Just like <a href="gconf-GConfClient.html#gconf-client-get"><code class="function">gconf_client_get()</code></a> but doesn't look for a default value if the key is unset.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key to get.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>newly-allocated <a href="gconf-gconf-value.html#GConfValue"><span class="type">GConfValue</span></a>, or <span class="symbol">NULL</span> if unset (even if a default exists).
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570759"></a><h3>
<a name="gconf-client-get-entry"></a>gconf_client_get_entry ()</h3>
<a class="indexterm" name="id2570770"></a><pre class="programlisting"><a href="gconf-gconf-value.html#GConfEntry">GConfEntry</a>* gconf_client_get_entry (GConfClient *client,
const gchar *key,
const gchar *locale,
gboolean use_schema_default,
GError **err);</pre>
<p>
Obtains the full <a href="gconf-gconf-value.html#GConfEntry"><span class="type">GConfEntry</span></a> for a value. Just like <a href="gconf-gconf.html#gconf-engine-get-entry"><code class="function">gconf_engine_get_entry()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td> key to get.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>locale</code></em> :</span></td>
<td>preferred locale (as in the locale-related environment variables).
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>use_schema_default</code></em> :</span></td>
<td>indicates whether to look for a default value when the key is unset.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a <a href="gconf-gconf-value.html#GConfEntry"><span class="type">GConfEntry</span></a>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2570964"></a><h3>
<a name="gconf-client-get-default-from-schema"></a>gconf_client_get_default_from_schema ()</h3>
<a class="indexterm" name="id2570976"></a><pre class="programlisting"><a href="gconf-gconf-value.html#GConfValue">GConfValue</a>* gconf_client_get_default_from_schema
(GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Returns the default value stored in the key's schema, if the key has a schema
associated and the schema exists and the schema contains a default value. Note
that <a href="gconf-GConfClient.html#gconf-client-get"><code class="function">gconf_client_get()</code></a>, <code class="function">gconf_engine_client_string()</code>, and so on already return the default value
if no other value is found, so normally you do not need this function. This
function is just for convenience; you could also get the <a href="gconf-gconf-value.html#GConfMetaInfo"><span class="type">GConfMetaInfo</span></a> for the
key, read the schema name from there, then look up the schema by name and
extract the default value. Just like <a href="gconf-gconf.html#gconf-engine-get-default-from-schema"><code class="function">gconf_engine_get_default_from_schema()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key to get.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>newly-allocated <a href="gconf-gconf-value.html#GConfValue"><span class="type">GConfValue</span></a>, or <span class="symbol">NULL</span> if the key has no default value in its schema.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2571158"></a><h3>
<a name="gconf-client-unset"></a>gconf_client_unset ()</h3>
<a class="indexterm" name="id2571170"></a><pre class="programlisting">gboolean gconf_client_unset (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Unsets the value of <em class="parameter"><code>key</code></em>; if <em class="parameter"><code>key</code></em> is already unset, has no effect. An
error of note is <code class="literal">GCONF_OVERRIDDEN</code>, indicating that the system
administrator has "forced" a value for this key.
Just like <a href="gconf-gconf.html#gconf-engine-unset"><code class="function">gconf_engine_unset()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key to unset.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2571331"></a><h3>
<a name="gconf-client-recursive-unset"></a>gconf_client_recursive_unset ()</h3>
<a class="indexterm" name="id2571342"></a><pre class="programlisting">gboolean gconf_client_recursive_unset (GConfClient *client,
const char *key,
GConfUnsetFlags flags,
GError **err);</pre>
<p>
Unsets all keys below <em class="parameter"><code>key</code></em>, including <em class="parameter"><code>key</code></em> itself. If any unset fails, continues on to unset
as much as it can. The first failure is returned in <em class="parameter"><code>err</code></em>. Just like <code class="function">gconf_engine_recursive_unset()</code>,
but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>a key or directory name to be unset.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>flags</code></em> :</span></td>
<td>change how the unset is done.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
<p>Since 2.4.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2571531"></a><h3>
<a name="gconf-client-all-entries"></a>gconf_client_all_entries ()</h3>
<a class="indexterm" name="id2571542"></a><pre class="programlisting">GSList* gconf_client_all_entries (GConfClient *client,
const gchar *dir,
GError **err);</pre>
<p>
Lists the key-value pairs in <em class="parameter"><code>dir</code></em>. Does not list subdirectories; for
that use <a href="gconf-GConfClient.html#gconf-client-all-dirs"><code class="function">gconf_client_all_dirs()</code></a>. The returned list contains <a href="gconf-gconf-value.html#GConfEntry"><span class="type">GConfEntry</span></a>
objects. A <a href="gconf-gconf-value.html#GConfEntry"><span class="type">GConfEntry</span></a> contains an <span class="emphasis"><em>absolute</em></span> key
and a value. The list is not recursive, it contains only the immediate
children of <em class="parameter"><code>dir</code></em>. To free the returned list, <a href="gconf-gconf-value.html#gconf-entry-free"><code class="function">gconf_entry_free()</code></a>
each list element, then <code class="function">g_slist_free()</code> the list itself.
Just like <a href="gconf-gconf.html#gconf-engine-all-entries"><code class="function">gconf_engine_all_entries()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dir</code></em> :</span></td>
<td>directory to list.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>List of <a href="gconf-gconf-value.html#GConfEntry"><span class="type">GConfEntry</span></a>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2571748"></a><h3>
<a name="gconf-client-all-dirs"></a>gconf_client_all_dirs ()</h3>
<a class="indexterm" name="id2571759"></a><pre class="programlisting">GSList* gconf_client_all_dirs (GConfClient *client,
const gchar *dir,
GError **err);</pre>
<p>
Lists the subdirectories in <em class="parameter"><code>dir</code></em>. The returned list contains allocated
strings. Each string is the absolute path of a subdirectory. You should <code class="function">g_free()</code> each string in the list, then <code class="function">g_slist_free()</code> the list itself.
Just like <a href="gconf-gconf.html#gconf-engine-all-dirs"><code class="function">gconf_engine_all_dirs()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dir</code></em> :</span></td>
<td>directory to get subdirectories from.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>List of allocated subdirectory names.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2571923"></a><h3>
<a name="gconf-client-suggest-sync"></a>gconf_client_suggest_sync ()</h3>
<a class="indexterm" name="id2571934"></a><pre class="programlisting">void gconf_client_suggest_sync (GConfClient *client,
GError **err);</pre>
<p>
Suggests to <span class="application">gconfd</span> that you've just finished
a block of changes, and it would be an optimal time to sync to
permanent storage. This is only a suggestion; and
<span class="application">gconfd</span> will eventually sync even if you
don't call <a href="gconf-gconf.html#gconf-engine-suggest-sync"><code class="function">gconf_engine_suggest_sync()</code></a>. This function is just a "hint"
provided to <span class="application">gconfd</span> to maximize efficiency
and minimize data loss.
Just like <a href="gconf-gconf.html#gconf-engine-suggest-sync"><code class="function">gconf_engine_suggest_sync()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572062"></a><h3>
<a name="gconf-client-dir-exists"></a>gconf_client_dir_exists ()</h3>
<a class="indexterm" name="id2572073"></a><pre class="programlisting">gboolean gconf_client_dir_exists (GConfClient *client,
const gchar *dir,
GError **err);</pre>
<p>
Queries whether the directory <em class="parameter"><code>dir</code></em> exists in the GConf
database. Returns <span class="symbol">TRUE</span> or <span class="symbol">FALSE</span>.
Just like <a href="gconf-gconf.html#gconf-engine-dir-exists"><code class="function">gconf_engine_dir_exists()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dir</code></em> :</span></td>
<td>directory to check for
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> or <span class="symbol">FALSE</span>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572229"></a><h3>
<a name="gconf-client-key-is-writable"></a>gconf_client_key_is_writable ()</h3>
<a class="indexterm" name="id2572240"></a><pre class="programlisting">gboolean gconf_client_key_is_writable (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Checks whether the key is writable.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>the value to be changed.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> if the key is writable, <span class="symbol">FALSE</span> if the key is read only.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572365"></a><h3>
<a name="gconf-client-get-float"></a>gconf_client_get_float ()</h3>
<a class="indexterm" name="id2572376"></a><pre class="programlisting">gdouble gconf_client_get_float (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Requests the floating point number (<code class="literal">GCONF_VALUE_FLOAT</code>) stored at
<em class="parameter"><code>key</code></em>. Automatically performs type-checking, so if a non-float is
stored at <em class="parameter"><code>key</code></em>, an error is returned. On error, or if <em class="parameter"><code>key</code></em> is unset,
0.0 is returned.
Just like <a href="gconf-gconf.html#gconf-engine-get-float"><code class="function">gconf_engine_get_float()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>the value of <em class="parameter"><code>key</code></em>, or 0.0 if no value is obtained.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572545"></a><h3>
<a name="gconf-client-get-int"></a>gconf_client_get_int ()</h3>
<a class="indexterm" name="id2572556"></a><pre class="programlisting">gint gconf_client_get_int (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Requests the integer (<code class="literal">GCONF_VALUE_INT</code>) stored at
<em class="parameter"><code>key</code></em>. Automatically performs type-checking, so if a non-integer is
stored at <em class="parameter"><code>key</code></em>, an error is returned. On error, or if <em class="parameter"><code>key</code></em> is unset,
0 is returned.
Just like <a href="gconf-gconf.html#gconf-engine-get-int"><code class="function">gconf_engine_get_int()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>the value of <em class="parameter"><code>key</code></em>, or 0 if no value is obtained.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572725"></a><h3>
<a name="gconf-client-get-string"></a>gconf_client_get_string ()</h3>
<a class="indexterm" name="id2572736"></a><pre class="programlisting">gchar* gconf_client_get_string (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Requests the string (<code class="literal">GCONF_VALUE_STRING</code>) stored at
<em class="parameter"><code>key</code></em>. Automatically performs type-checking, so if a non-string is
stored at <em class="parameter"><code>key</code></em>, an error is returned. On error, or if <em class="parameter"><code>key</code></em> is unset,
<span class="symbol">NULL</span> is returned.
Just like <a href="gconf-gconf.html#gconf-engine-get-string"><code class="function">gconf_engine_get_string()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>allocated string (value of <em class="parameter"><code>key</code></em>), or <span class="symbol">NULL</span> if no value is obtained.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572912"></a><h3>
<a name="gconf-client-get-bool"></a>gconf_client_get_bool ()</h3>
<a class="indexterm" name="id2572923"></a><pre class="programlisting">gboolean gconf_client_get_bool (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Requests the boolean value (<code class="literal">GCONF_VALUE_BOOL</code>) stored at
<em class="parameter"><code>key</code></em>. Automatically performs type-checking, so if a non-bool is
stored at <em class="parameter"><code>key</code></em>, an error is returned. On error, or if <em class="parameter"><code>key</code></em> is unset,
<span class="symbol">FALSE</span> is returned.
Just like <a href="gconf-gconf.html#gconf-engine-get-bool"><code class="function">gconf_engine_get_bool()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>the value of <em class="parameter"><code>key</code></em>, or <span class="symbol">FALSE</span> if no value is obtained.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2573099"></a><h3>
<a name="gconf-client-get-schema"></a>gconf_client_get_schema ()</h3>
<a class="indexterm" name="id2573110"></a><pre class="programlisting"><a href="gconf-gconf-schema.html#GConfSchema">GConfSchema</a>* gconf_client_get_schema (GConfClient *client,
const gchar *key,
GError **err);</pre>
<p>
Requests the schema (<code class="literal">GCONF_VALUE_SCHEMA</code>) stored at <em class="parameter"><code>key</code></em>.
Automatically performs type-checking, so if a non-schema is stored at
<em class="parameter"><code>key</code></em>, an error is returned. If no value is set or an error occurs,
<span class="symbol">NULL</span> is returned.
Just like <a href="gconf-gconf.html#gconf-engine-get-schema"><code class="function">gconf_engine_get_schema()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>the value of <em class="parameter"><code>key</code></em> as an allocated <a href="gconf-gconf-schema.html#GConfSchema"><span class="type">GConfSchema</span></a>, or <span class="symbol">NULL</span> if no value was obtained.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2573287"></a><h3>
<a name="gconf-client-get-list"></a>gconf_client_get_list ()</h3>
<a class="indexterm" name="id2573298"></a><pre class="programlisting">GSList* gconf_client_get_list (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> list_type,
GError **err);</pre>
<p>
Requests the list (<code class="literal">GCONF_VALUE_LIST</code>) stored at <em class="parameter"><code>key</code></em>. Automatically
performs type-checking, so if a non-list is stored at <em class="parameter"><code>key</code></em>, or the
list does not contain elements of type <em class="parameter"><code>list_type</code></em>, an error is
returned. If no value is set or an error occurs, <span class="symbol">NULL</span>
is returned. Note that <span class="symbol">NULL</span> is also the empty list,
so if you need to distinguish the empty list from an unset value, you
must use <a href="gconf-GConfClient.html#gconf-client-get"><code class="function">gconf_client_get()</code></a> to obtain a raw <a href="gconf-gconf-value.html#GConfValue"><span class="type">GConfValue</span></a>.
</p>
<p>
<span class="emphasis"><em>Remember that GConf lists can only store primitive types:
<code class="literal">GCONF_VALUE_FLOAT</code>, <code class="literal">GCONF_VALUE_INT</code>, <code class="literal">GCONF_VALUE_BOOL</code>,
<code class="literal">GCONF_VALUE_STRING</code>, <code class="literal">GCONF_VALUE_SCHEMA</code>.</em></span> Also remember
that lists must be uniform, you may not mix types in the same list.
</p>
<p>
The type of the list elements depends on <em class="parameter"><code>list_type</code></em>. A <a href="gconf-gconf-value.html#GConfValue"><span class="type">GConfValue</span></a>
with type <code class="literal">GCONF_VALUE_LIST</code> normally stores a list of more <a href="gconf-gconf-value.html#GConfValue"><span class="type">GConfValue</span></a>
objects. <a href="gconf-GConfClient.html#gconf-client-get-list"><code class="function">gconf_client_get_list()</code></a> automatically converts to primitive C
types. Thus, the list->data fields in the returned list
contain:
</p>
<div class="informaltable"><table width="100%" border="0">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td><code class="literal">GCONF_VALUE_INT</code></td>
<td>The integer itself, converted with <code class="function">GINT_TO_POINTER()</code>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_BOOL</code></td>
<td>The bool itself, converted with <code class="function">GINT_TO_POINTER()</code>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_FLOAT</code></td>
<td>A pointer to <span class="type">gdouble</span>, which should be freed with <code class="function">g_free()</code>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_STRING</code></td>
<td>A pointer to <span class="type">gchar</span>, which should be freed with <code class="function">g_free()</code>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_SCHEMA</code></td>
<td>A pointer to <a href="gconf-gconf-schema.html#GConfSchema"><span class="type">GConfSchema</span></a>, which should be freed with <a href="gconf-gconf-schema.html#gconf-schema-free"><code class="function">gconf_schema_free()</code></a>
</td>
</tr>
</tbody>
</table></div>
<p>
In the <code class="literal">GCONF_VALUE_FLOAT</code> and <code class="literal">GCONF_VALUE_STRING</code> cases, you must
<code class="function">g_free()</code> each list element. In the <code class="literal">GCONF_VALUE_SCHEMA</code> case you must
<a href="gconf-gconf-schema.html#gconf-schema-free"><code class="function">gconf_schema_free()</code></a> each element. In all cases you must free the
list itself with <code class="function">g_slist_free()</code>.
Just like <a href="gconf-gconf.html#gconf-engine-get-list"><code class="function">gconf_engine_get_list()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>list_type</code></em> :</span></td>
<td>type of each list element.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>an allocated list, with elements as described above.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2573800"></a><h3>
<a name="gconf-client-get-pair"></a>gconf_client_get_pair ()</h3>
<a class="indexterm" name="id2573811"></a><pre class="programlisting">gboolean gconf_client_get_pair (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> car_type,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> cdr_type,
gpointer car_retloc,
gpointer cdr_retloc,
GError **err);</pre>
<p>
Requests the pair (<code class="literal">GCONF_VALUE_PAIR</code>) stored at <em class="parameter"><code>key</code></em>. Automatically
performs type-checking, so if a non-pair is stored at <em class="parameter"><code>key</code></em>, or the
pair does not have the right <em class="parameter"><code>car_type</code></em> and <em class="parameter"><code>cdr_type</code></em>, an error is
returned. Remember that the <em class="firstterm">car</em> of a pair is
its first value, and the <em class="firstterm">cdr</em> is its second
value, in the Lisp tradition.
</p>
<p>
<span class="emphasis"><em>Remember that GConf pairs can only store primitive types:
<code class="literal">GCONF_VALUE_FLOAT</code>, <code class="literal">GCONF_VALUE_INT</code>, <code class="literal">GCONF_VALUE_BOOL</code>,
<code class="literal">GCONF_VALUE_STRING</code>, <code class="literal">GCONF_VALUE_SCHEMA</code>.</em></span>
</p>
<p>
<a href="gconf-GConfClient.html#gconf-client-get-pair"><code class="function">gconf_client_get_pair()</code></a> stores the two fields of the pair in the locations
pointed to by <em class="parameter"><code>car_retloc</code></em> and <em class="parameter"><code>cdr_retloc</code></em>. The type of these pointers
depends on the corresponding <em class="parameter"><code>car_type</code></em> and <em class="parameter"><code>cdr_type</code></em>:
</p>
<div class="informaltable"><table width="100%" border="0">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td><code class="literal">GCONF_VALUE_INT</code></td>
<td>pointer to <span class="type">gint</span>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_BOOL</code></td>
<td>pointer to <span class="type">gboolean</span>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_FLOAT</code></td>
<td>pointer to <span class="type">gdouble</span>
</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_STRING</code></td>
<td>pointer to <span class="type">gchar</span>*</td>
</tr>
<tr>
<td><code class="literal">GCONF_VALUE_SCHEMA</code></td>
<td>pointer to <a href="gconf-gconf-schema.html#GConfSchema"><span class="type">GConfSchema</span></a>*</td>
</tr>
</tbody>
</table></div>
<p>
In the <code class="literal">GCONF_VALUE_STRING</code> case, you must <code class="function">g_free()</code> the string(s)
stored in the return location(s). In the <code class="literal">GCONF_VALUE_SCHEMA</code> case you
must <a href="gconf-gconf-schema.html#gconf-schema-free"><code class="function">gconf_schema_free()</code></a> the returned schema. If there's an error
or the value is unset, <em class="parameter"><code>car_retloc</code></em> and <em class="parameter"><code>cdr_retloc</code></em> are left unchanged.
</p>
<p>
<a href="gconf-GConfClient.html#gconf-client-get-pair"><code class="function">gconf_client_get_pair()</code></a> returns <span class="symbol">TRUE</span> on success.
</p>
<p>
An example of <a href="gconf-GConfClient.html#gconf-client-get-pair"><code class="function">gconf_client_get_pair()</code></a> in action:
</p>
<pre class="programlisting">
gdouble car = 10.0;
gchar* cdr = NULL;
GError* error = NULL;
if (!gconf_client_get_pair(conf, "/foo",
GCONF_VALUE_FLOAT,
GCONF_VALUE_STRING,
&car, &cdr, &error))
{
/* Note: car/cdr should be untouched, because an error occurred */
g_assert(error != NULL);
fprintf(stderr, "Error: <code class="literal">s</code>\n", error->message);
g_error_free(error);
error = NULL;
}
else
{
/* Note: car/cdr may be untouched even though there was no error,
if no value was set for "/foo"
*/
printf("Found pair (<code class="literal">g</code>,<code class="literal">s</code>)\n", car, cdr);
if (cdr != NULL)
g_free(cdr);
}
</pre>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>car_type</code></em> :</span></td>
<td>desired type of the pair's first field (car).
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cdr_type</code></em> :</span></td>
<td>desired type of the pair's second field (cdr).
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>car_retloc</code></em> :</span></td>
<td>address of a return location for the car.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cdr_retloc</code></em> :</span></td>
<td>address of a return location for the cdr.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2574380"></a><h3>
<a name="gconf-client-set-float"></a>gconf_client_set_float ()</h3>
<a class="indexterm" name="id2574391"></a><pre class="programlisting">gboolean gconf_client_set_float (GConfClient *client,
const gchar *key,
gdouble val,
GError **err);</pre>
<p>
Change the value of <em class="parameter"><code>key</code></em> to <em class="parameter"><code>val</code></em>. Automatically creates the <em class="parameter"><code>key</code></em> if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a float (GCONF_VALUE_FLOAT), <a href="gconf-GConfClient.html#gconf-client-set-float"><code class="function">gconf_client_set_float()</code></a> will fail.
Just like <a href="gconf-gconf.html#gconf-engine-set"><code class="function">gconf_engine_set()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>val</code></em> :</span></td>
<td>new value of <em class="parameter"><code>key</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2574591"></a><h3>
<a name="gconf-client-set-int"></a>gconf_client_set_int ()</h3>
<a class="indexterm" name="id2574602"></a><pre class="programlisting">gboolean gconf_client_set_int (GConfClient *client,
const gchar *key,
gint val,
GError **err);</pre>
<p>
Change the value of <em class="parameter"><code>key</code></em> to <em class="parameter"><code>val</code></em>. Automatically creates the <em class="parameter"><code>key</code></em> if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store an integer (GCONF_VALUE_INT), <a href="gconf-GConfClient.html#gconf-client-set-int"><code class="function">gconf_client_set_int()</code></a> will fail.
Just like <a href="gconf-gconf.html#gconf-engine-set"><code class="function">gconf_engine_set()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>val</code></em> :</span></td>
<td>new value of <em class="parameter"><code>key</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2574802"></a><h3>
<a name="gconf-client-set-string"></a>gconf_client_set_string ()</h3>
<a class="indexterm" name="id2574813"></a><pre class="programlisting">gboolean gconf_client_set_string (GConfClient *client,
const gchar *key,
const gchar *val,
GError **err);</pre>
<p>
Change the value of <em class="parameter"><code>key</code></em> to <em class="parameter"><code>val</code></em>. Automatically creates the <em class="parameter"><code>key</code></em> if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a string (GCONF_VALUE_STRING), <a href="gconf-GConfClient.html#gconf-client-set-string"><code class="function">gconf_client_set_string()</code></a> will fail.
Just like <a href="gconf-gconf.html#gconf-engine-set"><code class="function">gconf_engine_set()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>val</code></em> :</span></td>
<td>new value of <em class="parameter"><code>key</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2575013"></a><h3>
<a name="gconf-client-set-bool"></a>gconf_client_set_bool ()</h3>
<a class="indexterm" name="id2575024"></a><pre class="programlisting">gboolean gconf_client_set_bool (GConfClient *client,
const gchar *key,
gboolean val,
GError **err);</pre>
<p>
Change the value of <em class="parameter"><code>key</code></em> to <em class="parameter"><code>val</code></em>. Automatically creates the <em class="parameter"><code>key</code></em> if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but but doesn't store a boolean (GCONF_VALUE_BOOL), <a href="gconf-GConfClient.html#gconf-client-set-bool"><code class="function">gconf_client_set_bool()</code></a> will fail.
Just like <a href="gconf-gconf.html#gconf-engine-set"><code class="function">gconf_engine_set()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>val</code></em> :</span></td>
<td>new value of <em class="parameter"><code>key</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2575224"></a><h3>
<a name="gconf-client-set-schema"></a>gconf_client_set_schema ()</h3>
<a class="indexterm" name="id2575235"></a><pre class="programlisting">gboolean gconf_client_set_schema (GConfClient *client,
const gchar *key,
const <a href="gconf-gconf-schema.html#GConfSchema">GConfSchema</a> *val,
GError **err);</pre>
<p>
Change the value of <em class="parameter"><code>key</code></em> to <em class="parameter"><code>val</code></em>. Automatically creates the <em class="parameter"><code>key</code></em> if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a schema value (GCONF_VALUE_SCHEMA), <a href="gconf-GConfClient.html#gconf-client-set-schema"><code class="function">gconf_client_set_schema()</code></a> will fail.
Just like <a href="gconf-gconf.html#gconf-engine-set"><code class="function">gconf_engine_set()</code></a>, but uses <span class="type">GConfClient</span> caching and error-handling features.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>val</code></em> :</span></td>
<td>new value of <em class="parameter"><code>key</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2575435"></a><h3>
<a name="gconf-client-set-list"></a>gconf_client_set_list ()</h3>
<a class="indexterm" name="id2575446"></a><pre class="programlisting">gboolean gconf_client_set_list (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> list_type,
GSList *list,
GError **err);</pre>
<p>
Changes the value of <em class="parameter"><code>key</code></em> to a <em class="parameter"><code>list</code></em> of type <em class="parameter"><code>list_type</code></em>. Automatically creates the <em class="parameter"><code>key</code></em> if it didn't exist before
(ie it was unset or it had a default value). If the key already exists but doesn't store a list value
(GCONF_VALUE_LIST), <a href="gconf-GConfClient.html#gconf-client-set-list"><code class="function">gconf_client_set_list()</code></a> will fail.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>list_type</code></em> :</span></td>
<td>type of each list element.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>list</code></em> :</span></td>
<td>new value of <em class="parameter"><code>key</code></em>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2575656"></a><h3>
<a name="gconf-client-set-pair"></a>gconf_client_set_pair ()</h3>
<a class="indexterm" name="id2575667"></a><pre class="programlisting">gboolean gconf_client_set_pair (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> car_type,
<a href="gconf-gconf-value.html#GConfValueType">GConfValueType</a> cdr_type,
gconstpointer address_of_car,
gconstpointer address_of_cdr,
GError **err);</pre>
<p>
Changes the value of <em class="parameter"><code>key</code></em> to a pair with the first field of type <em class="parameter"><code>car_type</code></em> and the second field of type <em class="parameter"><code>cdr_type</code></em>.
Automatically creates the key if it didn't exist before (ie it was unset or it had a default value). If the key
already exists but doesn't store a pair value (GCONF_VALUE_PAIR), <a href="gconf-GConfClient.html#gconf-client-set-pair"><code class="function">gconf_client_set_pair()</code></a> will fail.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key you want to set the value of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>car_type</code></em> :</span></td>
<td>type of the pair's first field (car).
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cdr_type</code></em> :</span></td>
<td>type of the pair's second field (cdr).
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>address_of_car</code></em> :</span></td>
<td>address of the car.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>address_of_cdr</code></em> :</span></td>
<td>address of the cdr.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> on error.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2575911"></a><h3>
<a name="gconf-client-error"></a>gconf_client_error ()</h3>
<a class="indexterm" name="id2575923"></a><pre class="programlisting">void gconf_client_error (GConfClient *client,
GError *error);</pre>
<p>
Emits the "error" signal. Rarely useful.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>error</code></em> :</span></td>
<td>error to pass to signal handlers.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2575998"></a><h3>
<a name="gconf-client-unreturned-error"></a>gconf_client_unreturned_error ()</h3>
<a class="indexterm" name="id2576010"></a><pre class="programlisting">void gconf_client_unreturned_error (GConfClient *client,
GError *error);</pre>
<p>
Emits the "unreturned_error" signal. Rarely useful.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>error</code></em> :</span></td>
<td>error to pass to signal handlers.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2576085"></a><h3>
<a name="gconf-client-value-changed"></a>gconf_client_value_changed ()</h3>
<a class="indexterm" name="id2576097"></a><pre class="programlisting">void gconf_client_value_changed (GConfClient *client,
const gchar *key,
<a href="gconf-gconf-value.html#GConfValue">GConfValue</a> *value);</pre>
<p>
Emits the "value_changed" signal. Rarely useful.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>key</code></em> :</span></td>
<td>key to pass to signal handlers.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>value</code></em> :</span></td>
<td>value of <em class="parameter"><code>key</code></em> to pass to signal handlers.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2576199"></a><h3>
<a name="gconf-client-commit-change-set"></a>gconf_client_commit_change_set ()</h3>
<a class="indexterm" name="id2576211"></a><pre class="programlisting">gboolean gconf_client_commit_change_set (GConfClient *client,
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a> *cs,
gboolean remove_committed,
GError **err);</pre>
<p>
Applies the changes in the change set to the <span class="type">GConfClient</span> passed as
the first argument. If <em class="parameter"><code>remove_committed</code></em> is <span class="symbol">TRUE</span>,
then any successfully-committed changes are removed from the change
set. If <em class="parameter"><code>remove_committed</code></em> is <span class="symbol">FALSE</span>, the
<a href="gconf-gconf-changeset.html#GConfChangeSet"><span class="type">GConfChangeSet</span></a> is left unmodified.
</p>
<p>
If any set or unset operation results in an error, then processing
terminates and the error is returned in <em class="parameter"><code>err</code></em> (unless <em class="parameter"><code>err</code></em> was
<span class="symbol">NULL</span>). If <em class="parameter"><code>remove_committed</code></em> was
<span class="symbol">TRUE</span>, then all the changes committed before the error
occurred will have been removed from the set. If any error occurs,
<span class="symbol">FALSE</span> is returned.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cs</code></em> :</span></td>
<td>a <a href="gconf-gconf-changeset.html#GConfChangeSet"><span class="type">GConfChangeSet</span></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>remove_committed</code></em> :</span></td>
<td>whether to remove successfully-committed changes from the set.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>
<span class="symbol">TRUE</span> on success, <span class="symbol">FALSE</span> if an error occurs.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2576438"></a><h3>
<a name="gconf-client-reverse-change-set"></a>gconf_client_reverse_change_set ()</h3>
<a class="indexterm" name="id2576449"></a><pre class="programlisting"><a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a>* gconf_client_reverse_change_set
(GConfClient *client,
<a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a> *cs,
GError **err);</pre>
<p>
Creates a change set that would reverse <em class="parameter"><code>cs</code></em>. That is, for each change in <em class="parameter"><code>cs</code></em>,
save the current state of that key in the returned change set.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>cs</code></em> :</span></td>
<td>change set to create the reverse of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a new change set that would restore the current state of each key in <em class="parameter"><code>cs</code></em>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2576589"></a><h3>
<a name="gconf-client-change-set-from-currentv"></a>gconf_client_change_set_from_currentv ()</h3>
<a class="indexterm" name="id2576601"></a><pre class="programlisting"><a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a>* gconf_client_change_set_from_currentv
(GConfClient *client,
const gchar **keys,
GError **err);</pre>
<p>
Creates a change set that will change the keys in
<span class="symbol">NULL</span>-terminated array <em class="parameter"><code>keys</code></em> to their current state. Use this to
save the current state of a collection of keys; then you can later revert to the
current state by committing the returned change set.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>keys</code></em> :</span></td>
<td>
<span class="symbol">NULL</span>-terminated array of key names.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>new change set that changes all the <em class="parameter"><code>keys</code></em> to their current state.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2576743"></a><h3>
<a name="gconf-client-change-set-from-current"></a>gconf_client_change_set_from_current ()</h3>
<a class="indexterm" name="id2576755"></a><pre class="programlisting"><a href="gconf-gconf-changeset.html#GConfChangeSet">GConfChangeSet</a>* gconf_client_change_set_from_current
(GConfClient *client,
GError **err,
const gchar *first_key,
...);</pre>
<p>
Convenient varargs version of <a href="gconf-GConfClient.html#gconf-client-change-set-from-currentv"><code class="function">gconf_client_change_set_from_currentv()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>client</code></em> :</span></td>
<td>a <span class="type">GConfClient</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>err</code></em> :</span></td>
<td>the return location for an allocated <span class="type">GError</span>, or <span class="symbol">NULL</span> to ignore errors.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>first_key</code></em> :</span></td>
<td>first key to save the current state of.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>...</code></em> :</span></td>
<td>
<span class="symbol">NULL</span>-terminated list of additional keys.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>new change set that changes all the keys to their current state.
</td>
</tr>
</tbody>
</table></div>
</div>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.id2568148" href="#id2568148">1</a>] </sup>
This is all a white lie; <span class="emphasis"><em>some</em></span> direct <a href="gconf-gconf-engine.html#GConfEngine"><span class="type">GConfEngine</span></a>
operations are safe. But it's complicated to know which, and if an operation
isn't safe the resulting bugs will mangle the cache and cause weird bugs at an
indeterminate time in the future; you don't want to risk this
situation.
</p></div>
</div>
</div>
<table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle">
<td align="left"><a accesskey="p" href="ch01.html"><b><< Using the GConf library</b></a></td>
<td align="right"><a accesskey="n" href="gconf-gconf-backend.html"><b>gconf-backend >></b></a></td>
</tr></table>
</body>
</html>