<!-- ##### SECTION Title ##### -->
GConfEngine

<!-- ##### SECTION Short_Description ##### -->

a GConf "database"

<!-- ##### SECTION Long_Description ##### -->
<para>
A #GConfEngine represents a connection to the GConf database. The
default #GConfEngine, returned from gconf_engine_get_default(), represents the
user's normal configuration source search path. Configuration-related
utilities, such as a configuration editor tool, might wish to access a
particular configuration source directly; they can obtain a
non-default #GConfEngine with gconf_engine_get_for_address().
</para>

<para>
Once you have a #GConfEngine, you can query and manipulate
configuration values.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GConfEngine ##### -->
<para>
An opaque data type representing one or more configuration sources.
</para>


<!-- ##### FUNCTION gconf_engine_get_default ##### -->
<para>
Returns the default #GConfEngine. All clients should use this, unless 
they are special configuration-related tools. The caller of this
function assumes one reference count, and must call
gconf_engine_unref() at some point. It's fairly important to unref the
#GConfEngine, to cleanly close the connection to
<application>gconfd</application>. So if possible close the connection
before exiting your application. see ? printf() <function>printf()</function>
</para>

@Returns: the default #GConfEngine.


<!-- ##### FUNCTION gconf_engine_get_for_address ##### -->
<para>
Obtains a special #GConfEngine; mostly useful for specialized
GConf-related tools. Normal clients shouldn't need to use it.
As with gconf_engine_get_default(), the returned #GConfEngine should be
unreferenced by the caller of this function.
</para>

@address: a configuration source address.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: a #GConfEngine.


<!-- ##### FUNCTION gconf_engine_get_for_addresses ##### -->
<para>
Similar to gconf_engine_get_for_address() , but takes a list of addresses 
instead of a single address.
</para>

@addresses: a list of configuration addresses.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: a #GConfEngine.
@Since: 2.4


<!-- ##### FUNCTION gconf_engine_unref ##### -->
<para>
Decreases the reference count of a #GConfEngine by one; if the
reference count reaches 0, destroys the #GConfEngine.
</para>

@conf: a #GConfEngine.


<!-- ##### FUNCTION gconf_engine_ref ##### -->
<para>
Increases the reference count of a #GConfEngine by one.
</para>

@conf: a #GConfEngine.


<!-- ##### FUNCTION gconf_engine_get_local ##### -->
<para>
Obtain a local (non-process-transparent) #GConfEngine. Local engines
do not support notification, and can only access config databases
directly (they do not use the multiple sources in a path system
supported by nonlocal engines).
</para>

@address: address of local database.
@err: return location of an allocated #GError.
@Returns: a #GConfEngine.


<!-- ##### FUNCTION gconf_engine_get_local_for_addresses ##### -->
<para>
Obtains a local #GConfEngine similar to gconf_engine_get_local ().
Instead of taking the address of the local database, this function takes
the addresses of the sources and gets the #GConfSources using gconf_sources_new_from_addresses ().
</para>

@addresses: a list of addresses of #GConfSources.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: a #GConfEngine.
@Since: 2.8


<!-- ##### FUNCTION gconf_engine_set_user_data ##### -->
<para>
Sets the user_data and the destroy notification function fields of a #GConfEngine.
</para>

@engine: a #GConfEngine.
@data: a #gpointer.
@dnotify: a pointer to the function to be called during destroy.


<!-- ##### FUNCTION gconf_engine_get_user_data ##### -->
<para>
Returns the user_data field of a #GConfEngine.
</para>

@engine: a #GConfEngine.
@Returns: a pointer to the user_data.


