<!-- ##### SECTION Title ##### -->
GConfValue, GConfEntry, GConfMetaInfo

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

A #GConfValue stores a dynamically-typed value. A #GConfEntry stores a
key-value pair.  A #GConfMetaInfo stores metainformation about a key.

<!-- ##### SECTION Long_Description ##### -->
<para>
#GConfValue stores one of the value types GConf understands; GConf
uses #GConfValue to pass values around because it doesn't know the
type of its values at compile time. 
</para>

<para>
A #GConfEntry pairs a relative key
name with a value, for example if the value "10" is stored at the key 
"/foo/bar/baz", the #GConfEntry will store "baz" and "10".
</para>

<para>
A #GConfMetaInfo object holds metainformation about a key, such as 
its last modification time and the name of the schema associated with
it. You should rarely if ever need to use #GConfMetaInfo.
(In fact you can't get the metainfo for a key using the current API.)
</para>

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

</para>

<!-- ##### ENUM GConfValueType ##### -->
<para>
Used to indicate the type of a #GConfValue.
</para>

@GCONF_VALUE_INVALID: Never the type of a #GConfValue obtained from GConf functions; used to indicate errors and the like.
@GCONF_VALUE_STRING: String value (#gchar*).
@GCONF_VALUE_INT: Integer value (#gint).
@GCONF_VALUE_FLOAT: Floating point value (#gdouble).
@GCONF_VALUE_BOOL: Boolean value (#gboolean).
@GCONF_VALUE_SCHEMA: Schema value (#GConfSchema).
@GCONF_VALUE_LIST: List of #GConfValue; #GConfValue elements must have
a primitive type (i.e. they may not be lists or pairs), and all elements
of a list must have the same type.
@GCONF_VALUE_PAIR: Pair of #GConfValue; the first field (car) and the second
field (cdr) may have different types. The two elements of a pair must be primitive
types, not lists or pairs.

<!-- ##### STRUCT GConfValue ##### -->
<para>
Represents a dynamically-typed value. The @type field tells you the
type of the value; the other fields should be accessed with the
accessor functions and macros.
</para>

<para>
<emphasis>A #GConfValue should always
be initialized before use. That is, you should not use a #GConfValue
unless you have called one of the functions beginning with
"gconf_value_set_".</emphasis>. For lists, initialization has two
steps: first you must set the list element type, then you must set the
list value.
</para>

@type: The #GConfValueType of this #GConfValue. The only field of
#GConfValue you should access directly.

<!-- ##### MACRO GCONF_VALUE_TYPE_VALID ##### -->
<para>

</para>

@x: 


<!-- ##### FUNCTION gconf_value_new ##### -->
<para>
Creates a new #GConfValue with type @type. The type is immutable after
creation; values have a fixed type. You <emphasis>must</emphasis>
initialize the #GConfValue after creation; that is, you must set its 
value with one of the "setter" functions.
</para>

@type: type of the new #GConfValue.
@Returns: newly-allocated #GConfValue.


<!-- ##### FUNCTION gconf_value_copy ##### -->
<para>
Copies a #GConfValue. The copy is a deep copy, that is, any allocated
memory inside the #GConfValue will also be copied.
</para>

@src: a #GConfValue to copy.
@Returns: a newly-allocated #GConfValue identical to @src.


<!-- ##### FUNCTION gconf_value_free ##### -->
<para>
Deallocates a #GConfValue. Also deallocates any allocated memory
inside the #GConfValue (such as lists, pair members, strings, and schemas).
</para>

@value: a #GConfValue to destroy.


<!-- ##### FUNCTION gconf_value_get_string ##### -->
<para>
Returns a <symbol>const gchar*</symbol> for a #GConfValue with type
%GCONF_VALUE_STRING. The returned string is <emphasis>not</emphasis> a
copy, don't try to free it. It is "owned" by the #GConfValue and will
be destroyed when the #GConfValue is destroyed.
</para>

<para>
If the #GConfValue is not initialized (i.e. no one has called
gconf_value_set_string()) then the string may be
<symbol>NULL</symbol>, but of course you should not try to use an
uninitialized #GConfValue.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_int ##### -->
<para>
Returns a #gint for a #GConfValue with type %GCONF_VALUE_INT. 
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_float ##### -->
<para>
Returns a #gdouble for a #GConfValue with type %GCONF_VALUE_FLOAT.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_list_type ##### -->
<para>
Returns the type of the list elements in a #GConfValue with type 
%GCONF_VALUE_LIST.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_list ##### -->
<para>
Returns a #GSList containing #GConfValue objects. Each #GConfValue in
the returned list will have the type returned by
gconf_value_get_list_type(). Remember that the empty #GSList is equal to
<symbol>NULL</symbol>.  The list is not a copy; it is "owned" by the
#GConfValue and will be destroyed when the #GConfValue is destroyed.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_car ##### -->
<para>
Returns the first member (car) of a #GConfValue with type
%GCONF_VALUE_PAIR. The car is another #GConfValue, with a primitive
type (bool, int, float, string, schema).
</para>

<para>
The returned value is not a copy; it is "owned" by the pair and will
be destroyed when the pair is destroyed.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_cdr ##### -->
<para>
Returns the second member (cdr) of a #GConfValue with type
%GCONF_VALUE_PAIR. The cdr is another #GConfValue, with a primitive
type (bool, int, float, string, schema).
</para>

<para>
The returned value is not a copy; it is "owned" by the pair and will
be destroyed when the pair is destroyed.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_bool ##### -->
<para>
Returns a #gboolean for a #GConfValue with type %GCONF_VALUE_BOOL. 
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_get_schema ##### -->
<para>
Returns a #GConfSchema for a #GConfValue with type
%GCONF_VALUE_SCHEMA. If the #GConfValue is uninitialized, it 
may return <symbol>NULL</symbol>; but of course you should have
initialized the #GConfValue. The GConf library will not return values
with a <symbol>NULL</symbol> schema.
</para>

<para>
The returned value is not a copy; it is "owned" by the #GConfValue and will
be destroyed when the #GConfValue is destroyed.
</para>

@value: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfValue.


<!-- ##### FUNCTION gconf_value_set_int ##### -->
<para>
Sets the value of a #GConfValue with type %GCONF_VALUE_INT.
</para>

@value: a #GConfValue of type %GCONF_VALUE_INT.
@the_int: the integer.


<!-- ##### FUNCTION gconf_value_set_string ##### -->
<para>
Sets the value of a #GConfValue with type
%GCONF_VALUE_STRING. @the_str is copied.
</para>

@value: a #GConfValue of type %GCONF_VALUE_STRING.
@the_str: the string.


<!-- ##### FUNCTION gconf_value_set_float ##### -->
<para>
Sets the value of a #GConfValue with type
%GCONF_VALUE_FLOAT. 
</para>

@value: a #GConfValue of type %GCONF_VALUE_FLOAT.
@the_float: the floating point number.


<!-- ##### FUNCTION gconf_value_set_bool ##### -->
<para>
Sets the value of a #GConfValue with type
%GCONF_VALUE_BOOL. 
</para>

@value: a #GConfValue of type %GCONF_VALUE_BOOL.
@the_bool: a boolean value (<symbol>TRUE</symbol> or <symbol>FALSE</symbol>).


<!-- ##### FUNCTION gconf_value_set_schema ##### -->
<para>
Sets the value of a #GConfValue with type %GCONF_VALUE_SCHEMA. The
#GConfSchema is copied. Alternatively you can use
gconf_value_set_schema_nocopy().
</para>

@value: a #GConfValue with type %GCONF_VALUE_SCHEMA.
@sc: the #GConfSchema.


<!-- ##### FUNCTION gconf_value_set_schema_nocopy ##### -->
<para>
Sets the value of a #GConfValue with type
%GCONF_VALUE_SCHEMA. The #GConfSchema is <emphasis>not</emphasis>
copied; the #GConfValue takes ownership of it, and it should only be
accessed via the gconf_value_get_schema() macro. This function is provided 
as a more efficient version of gconf_value_set_schema().
</para>

@value: a #GConfValue with type %GCONF_VALUE_SCHEMA.
@sc: the #GConfSchema.


<!-- ##### FUNCTION gconf_value_set_car ##### -->
<para>
Sets the value of the first field (car) of a #GConfValue with type
%GCONF_VALUE_PAIR. The #GConfValue is copied. Alternatively, use
gconf_value_set_car_nocopy().
</para>

@value: a #GConfValue with type %GCONF_VALUE_PAIR.
@car: the #GConfValue to set as the car of the pair.


<!-- ##### FUNCTION gconf_value_set_car_nocopy ##### -->
<para>
Sets the value of the first field (car) of a #GConfValue with type
%GCONF_VALUE_PAIR. The #GConfValue is <emphasis>not</emphasis> copied;
the #GConfValue takes ownership of it. Alternatively, use
gconf_value_set_car().
</para>

@value: a #GConfValue with type %GCONF_VALUE_PAIR.
@car: the #GConfValue to set as the car of the pair.


<!-- ##### FUNCTION gconf_value_set_cdr ##### -->
<para>
Sets the value of the second field (cdr) of a #GConfValue with type
%GCONF_VALUE_PAIR. The #GConfValue is copied. Alternatively, use
gconf_value_set_cdr_nocopy().
</para>

@value: a #GConfValue with type %GCONF_VALUE_PAIR.
@cdr: the #GConfValue to set as the cdr of the pair.


<!-- ##### FUNCTION gconf_value_set_cdr_nocopy ##### -->
<para>
Sets the value of the second field (cdr) of a #GConfValue with type
%GCONF_VALUE_PAIR. The #GConfValue is <emphasis>not</emphasis> copied;
the #GConfValue takes ownership of it. Alternatively, use
gconf_value_set_cdr().
</para>

@value: a #GConfValue with type %GCONF_VALUE_PAIR.
@cdr: the #GConfValue to set as the cdr of the pair.


<!-- ##### FUNCTION gconf_value_set_list_type ##### -->
<para>
Sets the type of the elements in a #GConfValue of type
%GCONF_VALUE_LIST. All the elements in the list must have the same
type. You must set the list type before you can set the list value.
</para>

@value: a #GConfValue with type %GCONF_VALUE_LIST.
@type: the type of elements in this list.


<!-- ##### FUNCTION gconf_value_set_list_nocopy ##### -->
<para>
Sets the value of a #GConfValue with type %GCONF_VALUE_LIST.  The
@list argument should be a #GSList of #GConfValue. Each #GConfValue in
the list must have the same type, and this type must be specified in
advance with gconf_value_set_list_type(). This function does
<emphasis>not</emphasis> copy the list; the #GConfValue will take
ownership of the list and its contents, and they will be destroyed
when the #GConfValue is destroyed. Alternatively, use
gconf_value_set_list() to make a copy.
</para>

@value: a #GConfValue with type %GCONF_VALUE_LIST.
@list: the #GSList of #GConfValue to set as the list value.


<!-- ##### FUNCTION gconf_value_set_list ##### -->
<para>
Sets the value of a #GConfValue with type %GCONF_VALUE_LIST.  The
@list argument should be a #GSList of #GConfValue. Each #GConfValue in
the list must have the same type, and this type must be specified in
advance with gconf_value_set_list_type(). This function copies the
list; it will not modify the @list argument.
</para>

@value: a #GConfValue with type %GCONF_VALUE_LIST.
@list: the #GSList of #GConfValue to set as the list value.


<!-- ##### FUNCTION gconf_value_to_string ##### -->
<para>
Creates a human-readable string representation of a #GConfValue. This
is intended for debugging and the like; the string representation is
not suitable for reliable machine parsing (that is, you shouldn't use
this function to save a value to a file or anything like that). The
exact nature of the string representation may change in future
versions. The returned string is newly-allocated and must be freed
with g_free().
</para>

@value: a #GConfValue.
@Returns: a newly-allocated string representing the #GConfValue.


<!-- ##### STRUCT GConfMetaInfo ##### -->
<para>

</para>

@schema: 
@mod_user: 
@mod_time: 

<!-- ##### FUNCTION gconf_meta_info_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gconf_meta_info_free ##### -->
<para>

</para>

@gcmi: 


<!-- ##### FUNCTION gconf_meta_info_get_schema ##### -->
<para>

</para>

@gcmi: 
@Returns: 
<!-- # Unused Parameters # -->
@x: 


<!-- ##### FUNCTION gconf_meta_info_get_mod_user ##### -->
<para>

</para>

@gcmi: 
@Returns: 
<!-- # Unused Parameters # -->
@x: 


<!-- ##### FUNCTION gconf_meta_info_mod_time ##### -->
<para>

</para>

@gcmi: 
@Returns: 
<!-- # Unused Parameters # -->
@x: 


<!-- ##### FUNCTION gconf_meta_info_set_schema ##### -->
<para>

</para>

@gcmi: 
@schema_name: 


<!-- ##### FUNCTION gconf_meta_info_set_mod_user ##### -->
<para>

</para>

@gcmi: 
@mod_user: 


<!-- ##### FUNCTION gconf_meta_info_set_mod_time ##### -->
<para>

</para>

@gcmi: 
@mod_time: 


<!-- ##### STRUCT GConfEntry ##### -->
<para>
Stores an entry from a GConf "directory," including a key-value pair,
the name of the schema applicable to this entry, whether the value is
a default value, and whether GConf can write a new value at this
key. @key should be an absolute key, not a relative key.  (Note that
internally GConf breaks this rule sometimes; but in the public
interface, @key is always an absolute key.)  To access the key and
value, use gconf_entry_get_key() and gconf_entry_get_value().
</para>

<warning><para>Value can be <symbol>NULL</symbol>, indicating that the
value is not set.</para></warning>

@key: an absolute key name
@value: 

<!-- ##### FUNCTION gconf_entry_new_nocopy ##### -->
<para>
Creates a new #GConfEntry with key @key and value @val. @key should be a full
path to the key, starting with '/'. Neither the key nor the value is copied;
both are freed when the #GConfEntry is freed. The string will be freed with
g_free() so should be allocated with a GLib function, not malloc().
</para>

@key: the key name
@val: the value
@Returns: a new #GConfentry.


<!-- ##### FUNCTION gconf_entry_free ##### -->
<para>
Destroys a #GConfEntry, freeing the key, the value, and the entry itself.
</para>

@entry: a #GConfEntry to free.


<!-- ##### FUNCTION gconf_entry_get_key ##### -->
<para>
Accesses the @key field of a #GConfEntry. The returned key is not a
copy, and should not be freed or modified.
</para>

@entry: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfEntry.


<!-- ##### FUNCTION gconf_entry_get_value ##### -->
<para>
Accesses the @value field of a #GConfEntry. The returned value is not
a copy, and should not be freed or modified. If you have called
gconf_entry_steal_value(), the returned value will be
<symbol>NULL</symbol>.
</para>

@entry: 
@Returns: 
<!-- # Unused Parameters # -->
@x: a #GConfEntry.


<!-- ##### FUNCTION gconf_entry_steal_value ##### -->
<para>
Extracts the value from a #GConfEntry, leaving the @value field in
#GConfEntry set to <symbol>NULL</symbol>. Destroying the #GConfEntry
will <emphasis>not</emphasis> destroy the value; the caller of
gconf_entry_steal_value() assumes ownership of it.
</para>

@entry: a #GConfEntry.
@Returns: a #GConfValue that the caller must free.


<!-- ##### FUNCTION gconf_entry_get_is_default ##### -->
<para>

</para>

@entry: 
@Returns: 
<!-- # Unused Parameters # -->
@x: 


<!-- ##### FUNCTION gconf_entry_get_schema_name ##### -->
<para>

</para>

@entry: 
@Returns: 
<!-- # Unused Parameters # -->
@x: 


<!-- ##### FUNCTION gconf_entry_set_is_default ##### -->
<para>

</para>

@entry: 
@is_default: 


<!-- ##### FUNCTION gconf_entry_set_schema_name ##### -->
<para>

</para>

@entry: 
@name: 


<!-- ##### FUNCTION gconf_entry_set_value_nocopy ##### -->
<para>

</para>

@entry: 
@val: 


