path: root/doc/gconf/tmpl/gconf-value.sgml

<!-- ##### 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>

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


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


<!-- ##### 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_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: a #GConfValue.
@Returns: a const char*.


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

@value: a #GConfValue.
@Returns: a #gint.


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

@value: a #GConfValue.
@Returns: a #gdouble.


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

@value: a #GConfValue.
@Returns: the type of the list elements (a primitive type).


<!-- ##### FUNCTION gconf_value_get_list ##### -->
<para>

</para>

@value: 
@Returns: 


<!-- ##### 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: a #GConfValue.
@Returns: the first member of a pair, a primitive type.


<!-- ##### 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: a #GConfValue.
@Returns: the second member of a pair, a primitive type.


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

@value: a #GConfValue.
@Returns: a #gboolean value.


<!-- ##### 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: a #GConfValue.
@Returns: a #GConfSchema.


<!-- ##### 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_new_from_string ##### -->
<para>
Creates a new #GConfValue with type @type and value set to the string passed.
Based on the value of @type, this function does the appropriate conversion of the
string passed to the @type, does error checks to ensure the value is valid, and
then calls the appropriate gconf_set function depending on the @type to set the value.
</para>

@type: type of the new #GConfValue.
@str: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@err: the value to be set.
@Returns: the value to be set.


<!-- ##### 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_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>
Creates a new #GConfMetaInfo structure and returns the newly allocated 
#GConfMetaInfo.
</para>

@void: 
@Returns: the newly allocated #GConfMetainfo.


<!-- ##### FUNCTION gconf_meta_info_free ##### -->
<para>
Frees the #GConfMetaInfo.
</para>

@gcmi: the #GConfMetaInfo to be freed.


<!-- ##### FUNCTION gconf_meta_info_get_schema ##### -->
<para>
Returns the schema field of the #GConfMetaInfo.
</para>

@gcmi: a #GConfMetaInfo.
@Returns: the schema field, a char* value.


<!-- ##### FUNCTION gconf_meta_info_get_mod_user ##### -->
<para>
Returns the user owning the daemon that made the last modification of the key.
</para>

@gcmi: a #GConfMetaInfo.
@Returns: mod_user, a char* value.


<!-- ##### FUNCTION gconf_meta_info_mod_time ##### -->
<para>
Returns the last modification time of the key.
</para>

@gcmi: a #GConfMetaInfo.
@Returns: the mod_time, a #GTime value.


<!-- ##### FUNCTION gconf_meta_info_set_schema ##### -->
<para>
Sets the schema_name field of the #GConfMetaInfo to the name passed.
</para>

@gcmi: a #GConfMetaInfo.
@schema_name: the name to be set for the schema, a gchar* value.


<!-- ##### FUNCTION gconf_meta_info_set_mod_user ##### -->
<para>
Sets the mod_user field of the #GConfMetaInfo to the user name passed.
</para>

@gcmi: a #GConfMetaInfo.
@mod_user: the value to be set, a char*.


<!-- ##### FUNCTION gconf_meta_info_set_mod_time ##### -->
<para>
Sets the mod_last field of the #GConfMetaInfo to the mod_time passed.
</para>

@gcmi: a #GConfMetaInfo.
@mod_time: a #GTime.


<!-- ##### 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: the value.

<!-- ##### 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: a #GConfEntry.
@Returns: the key , a char*.


<!-- ##### 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: a #GConfEntry.
@Returns: a #GConfValue.


<!-- ##### FUNCTION gconf_entry_get_schema_name ##### -->
<para>
Returns the schema_name field of the #GConfEntry. 
</para>

@entry: a #GConfEntry.
@Returns: the schema_name , a char* value.


<!-- ##### FUNCTION gconf_entry_get_is_default ##### -->
<para>
Returns the is_default field of the #GConfEntry , a gboolean value.
</para>

@entry: a #GConfEntry.
@Returns: a #gboolean value.


<!-- ##### FUNCTION gconf_entry_get_is_writable ##### -->
<para>
Returns the is_writable field of the #GConfEntry, a gboolean value.
</para>

@entry: a #GConfEntry.
@Returns: a #gboolean value.


<!-- ##### FUNCTION gconf_entry_new ##### -->
<para>
Creates a new #GConfEntry with key @key and value @val calling gconf_entry_new_nocopy ().
</para>

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


<!-- ##### 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_copy ##### -->
<para>
Copies the fields of an existing #GConfEntry and returns the new #GConfEntry.
</para>

@src: the #GConfEntry to be copied.
@Returns: the 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_ref ##### -->
<para>
Increases the refcount of a #GConfEntry by one.
</para>

@entry: a #GConfEntry.
@Returns: the referenced #GConfEntry.


<!-- ##### FUNCTION gconf_entry_unref ##### -->
<para>
Decreases the refcount of a #GConfEntry by one and  frees the
#GConfEntry when the refcount becomes zero.
</para>

@entry: 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_set_value ##### -->
<para>
Sets the value field of the #GConfEntry to the #GConfValue passed.
</para>

@entry: a #GConfEntry.
@val: a #GConfValue.


<!-- ##### FUNCTION gconf_entry_set_value_nocopy ##### -->
<para>
Sets the value field to @val after freeing the already existing value.
</para>

@entry: a #GConfEntry.
@val: the #GConfValue to be set.


<!-- ##### FUNCTION gconf_entry_set_schema_name ##### -->
<para>
Sets the schema_name field of the #GConfEntry to the name passed after freeing
the already existing name.
</para>

@entry: a #GConfEntry.
@name: the name to be set for the schema, a gchar* value.


<!-- ##### FUNCTION gconf_entry_set_is_default ##### -->
<para>
Sets the is_default field of the #GConfEntry to the boolean value passed.
</para>

@entry: a #GConfEntry.
@is_default: the boolean value to be set.


<!-- ##### FUNCTION gconf_entry_set_is_writable ##### -->
<para>
Sets the is_writable field of the #GConfEntry to the boolean value passed.
</para>

@entry: a #GConfEntry.
@is_writable: a boolean value.