<!-- ##### SECTION Title ##### -->
MateConf Core Interfaces

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

Basic functions to initialize MateConf and get/set values

<!-- ##### SECTION Long_Description ##### -->
<para>
These functions initialize MateConf, and communicate with the
<application>mateconfd</application> server via a
#MateConfEngine object. You can install a notification
request on the server, get values, set values, list directories, and associate
schema names with keys.
</para>

<para>
Most of this interface is replicated in the #GObject wrapper
(#MateConfClient object); an alternative to the value-setting functions
is the #MateConfChangeSet interface.
</para>

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

</para>

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


<!-- ##### SECTION Image ##### -->


<!-- ##### FUNCTION mateconf_init ##### -->
<para>
Initializes the MateConf library. Creates a connection to a CORBA ORB, and
initializes OAF (the object activation framework) if it isn't already
initialized.
</para>

@argc: 
@argv: 
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> otherwise.


<!-- ##### FUNCTION mateconf_preinit ##### -->
<para>

</para>

@app: 
@mod_info: 


<!-- ##### FUNCTION mateconf_postinit ##### -->
<para>

</para>

@app: 
@mod_info: 


<!-- ##### FUNCTION mateconf_is_initialized ##### -->
<para>
Asks whether the library has been initialized.
</para>

@void: 
@Returns: <symbol>TRUE</symbol> if the library has been initialized.


<!-- ##### USER_FUNCTION MateConfNotifyFunc ##### -->
<para>
A callback function invoked when a key's value changes. The @cnxn_id parameter
will be the connection ID returned from mateconf_engine_notify_add(). @key will be the
full path of the changed key, @value will be the new value if the key is set.
If the key is unset, @value will be the default value if one exists, or
<symbol>NULL</symbol> otherwise. @is_default indicates whether a value is a
default setting or a user setting. If @value is <symbol>NULL</symbol>,
@is_default will be <symbol>TRUE</symbol>. @user_data is the data passed to
mateconf_engine_notify_add().
</para>

@conf: the #MateConfEngine passed to mateconf_engine_notify_add().
@cnxn_id: the ID returned from mateconf_engine_notify_add().
@entry: 
@user_data: the user data passed to mateconf_engine_notify_add().
<!-- # Unused Parameters # -->
@key: the full path of the changed key.
@value: the new value, or <symbol>NULL</symbol> if the key was unset.
@is_default: if <symbol>TRUE</symbol>, the key is unset but this is the default value for it.


<!-- ##### FUNCTION mateconf_engine_notify_add ##### -->
<para>

</para>

@conf: 
@namespace_section: 
@func: 
@user_data: 
@err: 
@Returns: 


<!-- ##### FUNCTION mateconf_engine_notify_remove ##### -->
<para>
Removes a notification request.
</para>

@conf: the #MateConfEngine you were monitoring for changes.
@cnxn: The ID returned by mateconf_engine_notify_add().


<!-- ##### FUNCTION mateconf_engine_get ##### -->
<para>
Returns the #MateConfValue stored at @key, or <symbol>NULL</symbol> if no value is
set. You must call mateconf_value_free() to free the returned value. If you know
the expected type of the value, you probably want to use the type-specific
convenience wrappers (mateconf_engine_get_int(), etc.)  because they will do the
type-checking for you and return the appropriate type. Automatically returns the
default value for a key, if the key is unset and a default exists.
</para>

@conf: a #MateConfEngine to get the value from.
@key: the key to get.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: newly-allocated #MateConfValue, or <symbol>NULL</symbol> if unset and no default exists.


<!-- ##### FUNCTION mateconf_engine_get_without_default ##### -->
<para>
Identical to mateconf_engine_get (), except that it will return <symbol>NULL</symbol> in
place of the default value if the key is unset. Note that mateconf_engine_get () can also
return <symbol>NULL</symbol> if no default exists or an error occurs.
</para>

@conf: a #MateConfEngine to get the value from.
@key: the key to get.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: newly-allocated #MateConfValue, or <symbol>NULL</symbol> if unset.


<!-- ##### FUNCTION mateconf_engine_get_entry ##### -->
<para>
Obtain the full #MateConfEntry for a value.
</para>

@conf: a #MateConfEngine.
@key: the key to get.
@locale: preferred locale (as in the locale-related environment variables).
@use_schema_default: a #gboolean value indicating whether the default value associated with schema
should be used.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: a #MateConfEntry.


<!-- ##### FUNCTION mateconf_engine_get_with_locale ##### -->
<para>
Requests the value appropriate for a particular locale. Right now,
only values of type %MATECONF_VALUE_SCHEMA are localized; the locale is
meaningless for other value types. Also, mateconf_engine_get () automatically
requests the value in the user's current locale. So this function is
only useful if you want a schema for some locale other than the user's
current locale. Except for the additional argument, this function is
identical to mateconf_engine_get () in all respects.
</para>

@conf: a #MateConfEngine to get the value from.
@key: the key to get.
@locale: preferred locale (as in the locale-related environment variables).
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: newly-allocated #MateConfValue, or <symbol>NULL</symbol> if unset.


<!-- ##### FUNCTION mateconf_engine_get_default_from_schema ##### -->
<para>
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 mateconf_engine_get (), mateconf_engine_get_string(), 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 #MateConfMetaInfo for the
key, read the schema name from there, then look up the schema by name and
extract the default value.
</para>

@conf: a #MateConfEngine to get the value from.
@key: the key to get the default value for.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: newly-allocated #MateConfValue, or <symbol>NULL</symbol> if unset.


<!-- ##### FUNCTION mateconf_engine_set ##### -->
<para>
Sets the value of @key to @value. Does not modify the passed-in
#MateConfValue, you must free it yourself. You may prefer a type-specific
convenience wrapper, such as mateconf_engine_set_int().
</para>

<para>
 An error of note is %MATECONF_OVERRIDDEN, indicating that the system
administrator has "forced" a value for this key. If no writable
configuration sources exist, it is not an error, but MateConf will just
forget all your values; this allows users to have a configuration-free
setup without a constant barrage of error messages.
</para>

@conf: a #MateConfEngine to set the value in.
@key: the key to set.
@value: the new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_unset ##### -->
<para>
Unsets the value of @key; if @key is already unset, has no effect.  An
error of note is %MATECONF_OVERRIDDEN, indicating that the system
administrator has "forced" a value for this key.
</para>

@conf: a #MateConfEngine to affect.
@key: the key to unset.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_associate_schema ##### -->
<para>
Directs MateConf to find the schema for @key at location
@schema_key. That is, the value stored at @schema_key should have type
#MATECONF_VALUE_SCHEMA, and be descriptive of @key. Normally you don't
call this function from C code; you can ship a special file with your
application and ask <application>mateconftool</application> to install
schema associations into the database during "make install."
</para>

@conf: a #MateConfEngine to affect.
@key: the key to associate the schema with.
@schema_key: the key where the schema will be stored.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_all_entries ##### -->
<para>

</para>

@conf: 
@dir: 
@err: 
@Returns: 


<!-- ##### FUNCTION mateconf_engine_all_dirs ##### -->
<para>

</para>

@conf: 
@dir: 
@err: 
@Returns: 


<!-- ##### FUNCTION mateconf_engine_suggest_sync ##### -->
<para>
Suggests to <application>mateconfd</application> 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
<application>mateconfd</application> will eventually sync even if you
don't call mateconf_engine_suggest_sync(). This function is just a "hint"
provided to <application>mateconfd</application> to maximize efficiency
and minimize data loss.
</para>

@conf: the #MateConfEngine to suggest syncing to.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.


<!-- ##### FUNCTION mateconf_engine_dir_exists ##### -->
<para>
Queries whether the directory @dir exists in the MateConf
database. Returns <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
</para>

@conf: a #MateConfEngine.
@dir: Directory to check for.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.


<!-- ##### FUNCTION mateconf_engine_remove_dir ##### -->
<para>
This function first checks the validity of the mateconf key. In case of a local #MateConfEngine it removes
the directory from the source backend calling mateconf_sources_remove_dir (). Otherwise it obtains the
configuration database using mateconf_engine_get_database () and removes the directory from the database
calling ConfigDatabase_remove_dir ().
</para>

@conf: a #MateConfEngine.
@dir: the name of the directory to be removed.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.


<!-- ##### FUNCTION mateconf_engine_key_is_writable ##### -->
<para>
Checks whether the key is writable.
</para>

@conf: a #MateConfEngine.
@key: the value to be changed.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> if the key is writable, <symbol>FALSE</symbol> if the key is read only.


<!-- ##### FUNCTION mateconf_valid_key ##### -->
<para>
Asks whether a key is syntactically correct, that is, it ensures that
the key consists of slash-separated strings and contains only legal
characters. Normally you shouldn't need to call this function; the
MateConf functions all check this for you and return an error if the key
is invalid. However, it may be useful to validate input to an entry
field or the like. If you pass a non-<symbol>NULL</symbol> address as
the @why_invalid argument, an allocated string is returned explaining
why the key is invalid, if it is. If the key is valid the @why_invalid
argument is unused.
</para>

@key: key to check.
@why_invalid: return location for an explanation of the problem, if any. g_free() the returned string.
@Returns: <symbol>TRUE</symbol> if the key is valid, or <symbol>FALSE</symbol> if not.


<!-- ##### FUNCTION mateconf_key_is_below ##### -->
<para>
Asks whether the key @below would be found below the key @above, were
they both to exist in the database. For example, <symbol>/foo</symbol>
is always found below <symbol>/</symbol> and above
<symbol>/foo/bar</symbol>. This probably isn't useful but MateConf uses
it internally so here it is if you need it.
</para>

@above: the key on the "left hand side" of the predicate.
@below: the key on the "right hand side."
@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.


<!-- ##### FUNCTION mateconf_concat_dir_and_key ##### -->
<para>
Concatenates the dir and key passed removing the unnecessary '/' characters
and returns the new string.
</para>

@dir: the directory.
@key: the key.
@Returns: the newly concatenated string.


<!-- ##### FUNCTION mateconf_unique_key ##### -->
<para>
Generates a new and unique key using serial number, process id, current time and a 
random number generated.
</para>

@void: 
@Returns: a newly created key, a #gchar value.


<!-- ##### FUNCTION mateconf_escape_key ##### -->
<para>

</para>

@arbitrary_text: 
@len: 
@Returns: 


<!-- ##### FUNCTION mateconf_unescape_key ##### -->
<para>

</para>

@escaped_key: 
@len: 
@Returns: 


<!-- ##### FUNCTION mateconf_engine_get_float ##### -->
<para>
Requests the floating point number (%MATECONF_VALUE_FLOAT) stored at
@key. Automatically performs type-checking, so if a non-float is
stored at @key, an error is returned. On error, or if @key is unset, 
0.0 is returned.
</para>

@conf: a #MateConfEngine.
@key: key you want the value of.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: the value of @key, or 0.0 if no value is obtained.


<!-- ##### FUNCTION mateconf_engine_get_int ##### -->
<para>
Requests the integer (%MATECONF_VALUE_INT) stored at
@key. Automatically performs type-checking, so if a non-integer is
stored at @key, an error is returned. On error, or if @key is unset, 
0 is returned.
</para>

@conf: a #MateConfEngine.
@key: key you want the value of.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: the value of @key, or 0 if no value is obtained.


<!-- ##### FUNCTION mateconf_engine_get_string ##### -->
<para>
Requests the string (%MATECONF_VALUE_STRING) stored at
@key. Automatically performs type-checking, so if a non-string is
stored at @key, an error is returned. On error, or if @key is unset, 
<symbol>NULL</symbol> is returned.
</para>

@conf: a #MateConfEngine.
@key: key you want the value of.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: allocated string (value of @key), or <symbol>NULL</symbol> if no value is obtained.


<!-- ##### FUNCTION mateconf_engine_get_bool ##### -->
<para>
Requests the boolean value (%MATECONF_VALUE_BOOL) stored at
@key. Automatically performs type-checking, so if a non-bool is
stored at @key, an error is returned. On error, or if @key is unset, 
<symbol>FALSE</symbol> is returned.
</para>

@conf: a #MateConfEngine.
@key: key you want the value of.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: the value of @key, or <symbol>FALSE</symbol> if no value is obtained.


<!-- ##### FUNCTION mateconf_engine_get_schema ##### -->
<para>

</para>

@conf: 
@key: 
@err: 
@Returns: 


<!-- ##### FUNCTION mateconf_engine_get_list ##### -->
<para>

</para>

@conf: 
@key: 
@list_type: 
@err: 
@Returns: 


<!-- ##### FUNCTION mateconf_engine_get_pair ##### -->
<para>
Requests the pair (%MATECONF_VALUE_PAIR) stored at @key.  Automatically
performs type-checking, so if a non-pair is stored at @key, or the
pair does not have the right @car_type and @cdr_type, an error is
returned. Remember that the <firstterm>car</firstterm> of a pair is
its first value, and the <firstterm>cdr</firstterm> is its second
value, in the Lisp tradition. 
</para>

<para>
<emphasis>Remember that MateConf pairs can only store primitive types:
%MATECONF_VALUE_FLOAT, %MATECONF_VALUE_INT, %MATECONF_VALUE_BOOL,
%MATECONF_VALUE_STRING, %MATECONF_VALUE_SCHEMA.</emphasis>
</para>

<para>
mateconf_engine_get_pair() stores the two fields of the pair in the locations
pointed to by @car_retloc and @cdr_retloc. The type of these pointers
depends on the corresponding @car_type and @cdr_type:
 
<informaltable pgwide="1" frame="none">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>

<row>
<entry>%MATECONF_VALUE_INT</entry>
<entry>pointer to #gint</entry>
</row>

<row>
<entry>%MATECONF_VALUE_BOOL</entry>
<entry>pointer to #gboolean</entry>
</row>

<row>
<entry>%MATECONF_VALUE_FLOAT</entry>
<entry>pointer to #gdouble</entry>
</row>

<row>
<entry>%MATECONF_VALUE_STRING</entry>
<entry>pointer to #gchar*</entry>
</row>

<row>
<entry>%MATECONF_VALUE_SCHEMA</entry>
<entry>pointer to #MateConfSchema*</entry>
</row>

</tbody></tgroup></informaltable>

In the %MATECONF_VALUE_STRING case, you must g_free() the string(s)
stored in the return location(s). In the %MATECONF_VALUE_SCHEMA case you
must mateconf_schema_free() the returned schema. If there's an error
or the value is unset, @car_retloc and @cdr_retloc are left unchanged.
</para>

<para>
mateconf_engine_get_pair() returns <symbol>TRUE</symbol> on success.
</para>

<para>
An example of mateconf_engine_get_pair() in action:
<programlisting>
gdouble car = 10.0;
gchar* cdr  = NULL; 
GError* error = NULL;

if (!mateconf_engine_get_pair(conf, "/foo", 
                    MATECONF_VALUE_FLOAT,
                    MATECONF_VALUE_STRING, 
                    &amp;car, &amp;cdr, &amp;error))
  {
    /* Note: car/cdr should be untouched, because an error occurred */
    g_assert(error != NULL);
    fprintf(stderr, "Error: %s\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 (%g,%s)\n", car, cdr);
    if (cdr != NULL)
      g_free(cdr);
  }
</programlisting>
</para>

@conf: a #MateConfEngine.
@key: key you want the value of.
@car_type: desired type of the pair's first field (car).
@cdr_type: desired type of the pair's second field (cdr).
@car_retloc: address of a return location for the car.
@cdr_retloc: address of a return location for the cdr.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_float ##### -->
<para>
Change the value of @key to @val. Automatically creates the @key 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 (MATECONF_VALUE_FLOAT), mateconf_engine_set_float() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@val: new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_int ##### -->
<para>
Change the value of @key to @val. Automatically creates the @key 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 (MATECONF_VALUE_INT), mateconf_engine_set_int() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@val: new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_string ##### -->
<para>
Change the value of @key to @val. Automatically creates the @key 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 (MATECONF_VALUE_STRING), mateconf_engine_set_string() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@val: new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_bool ##### -->
<para>
Change the value of @key to @val. Automatically creates the @key 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 (MATECONF_VALUE_BOOL), mateconf_engine_set_bool() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@val: new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_schema ##### -->
<para>
Change the value of @key to @val. Automatically creates the @key 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 (MATECONF_VALUE_SCHEMA), mateconf_engine_set_schema() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@val: new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_list ##### -->
<para>
Change the value of @key to @list of type @list_type. Automatically creates the @key 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 list value 
(MATECONF_VALUE_LIST), mateconf_engine_set_list() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@list_type: type of each list element.
@list: new value of @key.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### FUNCTION mateconf_engine_set_pair ##### -->
<para>
Change the value of @key to a pair of first type @car_type and second type @cdr_type . Automatically creates the 
@key 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 (MATECONF_VALUE_SCHEMA), mateconf_engine_set_schema() will fail.
</para>

@conf: a #MateConfEngine.
@key: key you want to set the value of.
@car_type: type of the pair's first field (car).
@cdr_type: type of the pair's second field (cdr).
@address_of_car: address of the car.
@address_of_cdr: address of the cdr.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.


<!-- ##### STRUCT MateConfEnumStringPair ##### -->
<para>

</para>

@enum_value: 
@str: 

<!-- ##### FUNCTION mateconf_string_to_enum ##### -->
<para>
It's best to store enumeration values as strings rather than integers. This is
robust against changes in the enumeration, and also human-readable.
This function makes it more convenient to store enums as strings.
</para>

<para>
The first argument is a lookup table, typically declared statically as follows:
<programlisting>
static MateConfEnumStringPair foo_enum_lookup_table[] = {
  { FOO_BLAH, "Blah" },
  { FOO_BAR,  "Bar"  },
  { 0, NULL }
};
</programlisting>
Note that the last element of the table is <literal>{ 0, NULL }</literal>.
Typically the strings you use should be semi-human-readable, for GTK+ and MATE
stripping off the library prefix and converting to StudlyCaps is the recommended
convention.
</para>

<para>
The function returns <symbol>TRUE</symbol> if a match for the string is found,
and if a match is found the enum value is placed in @enum_value_retloc.
</para>

@lookup_table: a lookup table mapping enum values to strings.
@str: the string to convert to an enum value.
@enum_value_retloc: the address of an enum variable.
@Returns: <symbol>TRUE</symbol> if a match was found.


<!-- ##### FUNCTION mateconf_enum_to_string ##### -->
<para>
See mateconf_string_to_enum() for background information on this function.
</para>

@lookup_table: a lookup table mapping enum values to strings.
@enum_value: the enumeration value to convert to a string.
@Returns: a pointer to the proper string in the lookup table, or <symbol>NULL</symbol> if no match was found.


<!-- ##### FUNCTION mateconf_clear_cache ##### -->
<para>
In case of a local #MateConfEngine, this function calls mateconf_sources_clear_cache () to clear the
cache from the source. Otherwise it obtains the configuration database using mateconf_engine_get_database ()
and clears the configuration database cache using ConfigDatabase_clear_cache ().
</para>

@conf: a #MateConfEngine.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.


<!-- ##### FUNCTION mateconf_synchronous_sync ##### -->
<para>
In case of a local #MateConfEngine, this function syncs up all the mateconf sources calling
mateconf_synchronous_sync (). Otherwise it obtains the configuration database using
mateconf_engine_get_database () and syncs up the database calling ConfigDatabase_synchronous_sync ().
</para>

@conf: a #MateConfEngine.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.


<!-- ##### FUNCTION mateconf_engine_get_full ##### -->
<para>
Returns the #MateConfValue of a key and the associated #MateConfEntry fields depending on the parameters passed.
</para>

@conf: a #MateConfEngine.
@key: the key whose value is to be obtained.
@locale: the preferred locale (as in the locale related environment variables) or<symbol>NULL</symbol> if no locale is to be
passed.
@use_schema_default: a #gboolean value, indicating whether schema information is to be used as the default
value.
@is_default_p: a #gpointer if the is_default field of the #MateConfEntry is required, <symbol>NULL</symbol>
otherwise.
@is_writable_p: a #gpointer if the is_writable field of the #MateConfEntry is required, <symbol>NULL</symbol>
otherwise.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: the #MateConfValue.


