Top | ![]() |
![]() |
![]() |
![]() |
MateConfValue, MateConfEntry, MateConfMetaInfoMateConfValue, MateConfEntry, MateConfMetaInfo — A MateConfValue stores a dynamically-typed value. A MateConfEntry stores a key-value pair. A MateConfMetaInfo stores metainformation about a key. |
enum | MateConfValueType |
struct | MateConfValue |
struct | MateConfMetaInfo |
struct | MateConfEntry |
MateConfValue stores one of the value types MateConf understands; MateConf uses MateConfValue to pass values around because it doesn't know the type of its values at compile time.
A MateConfEntry pairs a relative key name with a value, for example if the value "10" is stored at the key "/foo/bar/baz", the MateConfEntry will store "baz" and "10".
A MateConfMetaInfo 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 MateConfMetaInfo. (In fact you can't get the metainfo for a key using the current API.)
#define MATECONF_VALUE_TYPE_VALID(x) (((x) > MATECONF_VALUE_INVALID) && ((x) <= MATECONF_VALUE_PAIR))
const char *
mateconf_value_get_string (const MateConfValue *value
);
Returns a const gchar* for a MateConfValue with type
MATECONF_VALUE_STRING
. The returned string is not a
copy, don't try to free it. It is "owned" by the MateConfValue and will
be destroyed when the MateConfValue is destroyed.
If the MateConfValue is not initialized (i.e. no one has called
mateconf_value_set_string()
) then the string may be
NULL, but of course you should not try to use an
uninitialized MateConfValue.
int
mateconf_value_get_int (const MateConfValue *value
);
Returns a gint for a MateConfValue with type MATECONF_VALUE_INT
.
double
mateconf_value_get_float (const MateConfValue *value
);
Returns a gdouble for a MateConfValue with type MATECONF_VALUE_FLOAT
.
MateConfValueType
mateconf_value_get_list_type (const MateConfValue *value
);
Returns the type of the list elements in a MateConfValue with type
MATECONF_VALUE_LIST
.
GSList *
mateconf_value_get_list (const MateConfValue *value
);
Returns a GSList containing MateConfValue objects. Each MateConfValue in
the returned list will have the type returned by
mateconf_value_get_list_type()
. Remember that the empty GSList is equal to
MateConfValue and will be destroyed when the MateConfValue is destroyed.
MateConfValue *
mateconf_value_get_car (const MateConfValue *value
);
Returns the first member (car) of a MateConfValue with type
MATECONF_VALUE_PAIR
. The car is another MateConfValue, with a primitive
type (bool, int, float, string, schema).
The returned value is not a copy; it is "owned" by the pair and will be destroyed when the pair is destroyed.
MateConfValue *
mateconf_value_get_cdr (const MateConfValue *value
);
Returns the second member (cdr) of a MateConfValue with type
MATECONF_VALUE_PAIR
. The cdr is another MateConfValue, with a primitive
type (bool, int, float, string, schema).
The returned value is not a copy; it is "owned" by the pair and will be destroyed when the pair is destroyed.
gboolean
mateconf_value_get_bool (const MateConfValue *value
);
Returns a gboolean for a MateConfValue with type MATECONF_VALUE_BOOL
.
MateConfSchema *
mateconf_value_get_schema (const MateConfValue *value
);
Returns a MateConfSchema for a MateConfValue with type
MATECONF_VALUE_SCHEMA
. If the MateConfValue is uninitialized, it
may return NULL; but of course you should have
initialized the MateConfValue. The MateConf library will not return values
with a NULL schema.
The returned value is not a copy; it is "owned" by the MateConfValue and will be destroyed when the MateConfValue is destroyed.
MateConfValue *
mateconf_value_new (MateConfValueType type
);
Creates a new MateConfValue with type type
. The type is immutable after
creation; values have a fixed type. You must
initialize the MateConfValue after creation; that is, you must set its
value with one of the "setter" functions.
MateConfValue * mateconf_value_new_from_string (MateConfValueType type
,const gchar *str
,GError **err
);
Creates a new MateConfValue 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 mateconf_set function depending on the type
to set the value.
type |
type of the new MateConfValue. |
|
str |
the return location for an allocated GError, or NULL to ignore errors. |
|
err |
the value to be set. |
MateConfValue *
mateconf_value_copy (const MateConfValue *src
);
Copies a MateConfValue. The copy is a deep copy, that is, any allocated memory inside the MateConfValue will also be copied.
void
mateconf_value_free (MateConfValue *value
);
Deallocates a MateConfValue. Also deallocates any allocated memory inside the MateConfValue (such as lists, pair members, strings, and schemas).
void mateconf_value_set_int (MateConfValue *value
,gint the_int
);
Sets the value of a MateConfValue with type MATECONF_VALUE_INT
.
void mateconf_value_set_string (MateConfValue *value
,const gchar *the_str
);
Sets the value of a MateConfValue with type
MATECONF_VALUE_STRING
. the_str
is copied.
void mateconf_value_set_float (MateConfValue *value
,gdouble the_float
);
Sets the value of a MateConfValue with type
MATECONF_VALUE_FLOAT
.
void mateconf_value_set_bool (MateConfValue *value
,gboolean the_bool
);
Sets the value of a MateConfValue with type
MATECONF_VALUE_BOOL
.
value |
a MateConfValue of type |
|
the_bool |
a boolean value (TRUE or FALSE). |
void mateconf_value_set_schema (MateConfValue *value
,const MateConfSchema *sc
);
Sets the value of a MateConfValue with type MATECONF_VALUE_SCHEMA
. The
MateConfSchema is copied. Alternatively you can use
mateconf_value_set_schema_nocopy()
.
void mateconf_value_set_schema_nocopy (MateConfValue *value
,MateConfSchema *sc
);
Sets the value of a MateConfValue with type
MATECONF_VALUE_SCHEMA
. The MateConfSchema is not
copied; the MateConfValue takes ownership of it, and it should only be
accessed via the mateconf_value_get_schema()
macro. This function is provided
as a more efficient version of mateconf_value_set_schema()
.
void mateconf_value_set_car (MateConfValue *value
,const MateConfValue *car
);
Sets the value of the first field (car) of a MateConfValue with type
MATECONF_VALUE_PAIR
. The MateConfValue is copied. Alternatively, use
mateconf_value_set_car_nocopy()
.
value |
a MateConfValue with type |
|
car |
the MateConfValue to set as the car of the pair. |
void mateconf_value_set_car_nocopy (MateConfValue *value
,MateConfValue *car
);
Sets the value of the first field (car) of a MateConfValue with type
MATECONF_VALUE_PAIR
. The MateConfValue is not copied;
the MateConfValue takes ownership of it. Alternatively, use
mateconf_value_set_car()
.
value |
a MateConfValue with type |
|
car |
the MateConfValue to set as the car of the pair. |
void mateconf_value_set_cdr (MateConfValue *value
,const MateConfValue *cdr
);
Sets the value of the second field (cdr) of a MateConfValue with type
MATECONF_VALUE_PAIR
. The MateConfValue is copied. Alternatively, use
mateconf_value_set_cdr_nocopy()
.
value |
a MateConfValue with type |
|
cdr |
the MateConfValue to set as the cdr of the pair. |
void mateconf_value_set_cdr_nocopy (MateConfValue *value
,MateConfValue *cdr
);
Sets the value of the second field (cdr) of a MateConfValue with type
MATECONF_VALUE_PAIR
. The MateConfValue is not copied;
the MateConfValue takes ownership of it. Alternatively, use
mateconf_value_set_cdr()
.
value |
a MateConfValue with type |
|
cdr |
the MateConfValue to set as the cdr of the pair. |
void mateconf_value_set_list_type (MateConfValue *value
,MateConfValueType type
);
Sets the type of the elements in a MateConfValue of type
MATECONF_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.
value |
a MateConfValue with type |
|
type |
the type of elements in this list. |
void mateconf_value_set_list_nocopy (MateConfValue *value
,GSList *list
);
Sets the value of a MateConfValue with type MATECONF_VALUE_LIST
. The
list
argument should be a GSList of MateConfValue. Each MateConfValue in
the list must have the same type, and this type must be specified in
advance with mateconf_value_set_list_type()
. This function does
not copy the list; the MateConfValue will take
ownership of the list and its contents, and they will be destroyed
when the MateConfValue is destroyed. Alternatively, use
mateconf_value_set_list()
to make a copy.
value |
a MateConfValue with type |
|
list |
the GSList of MateConfValue to set as the list value. |
void mateconf_value_set_list (MateConfValue *value
,GSList *list
);
Sets the value of a MateConfValue with type MATECONF_VALUE_LIST
. The
list
argument should be a GSList of MateConfValue. Each MateConfValue in
the list must have the same type, and this type must be specified in
advance with mateconf_value_set_list_type()
. This function copies the
list; it will not modify the list
argument.
value |
a MateConfValue with type |
|
list |
the GSList of MateConfValue to set as the list value. |
gchar *
mateconf_value_to_string (const MateConfValue *value
);
Creates a human-readable string representation of a MateConfValue. 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()
.
MateConfMetaInfo *
mateconf_meta_info_new (void
);
Creates a new MateConfMetaInfo structure and returns the newly allocated MateConfMetaInfo.
void
mateconf_meta_info_free (MateConfMetaInfo *gcmi
);
Frees the MateConfMetaInfo.
const char *
mateconf_meta_info_get_schema (MateConfMetaInfo *gcmi
);
Returns the schema field of the MateConfMetaInfo.
const char *
mateconf_meta_info_get_mod_user (MateConfMetaInfo *gcmi
);
Returns the user owning the daemon that made the last modification of the key.
GTime
mateconf_meta_info_mod_time (MateConfMetaInfo *gcmi
);
Returns the last modification time of the key.
void mateconf_meta_info_set_schema (MateConfMetaInfo *gcmi
,const gchar *schema_name
);
Sets the schema_name field of the MateConfMetaInfo to the name passed.
void mateconf_meta_info_set_mod_user (MateConfMetaInfo *gcmi
,const gchar *mod_user
);
Sets the mod_user field of the MateConfMetaInfo to the user name passed.
void mateconf_meta_info_set_mod_time (MateConfMetaInfo *gcmi
,GTime mod_time
);
Sets the mod_last field of the MateConfMetaInfo to the mod_time passed.
const char *
mateconf_entry_get_key (const MateConfEntry *entry
);
Accesses the key
field of a MateConfEntry. The returned key is not a
copy, and should not be freed or modified.
MateConfValue *
mateconf_entry_get_value (const MateConfEntry *entry
);
Accesses the value
field of a MateConfEntry. The returned value is not
a copy, and should not be freed or modified. If you have called
mateconf_entry_steal_value()
, the returned value will be
NULL.
const char *
mateconf_entry_get_schema_name (const MateConfEntry *entry
);
Returns the schema_name field of the MateConfEntry.
gboolean
mateconf_entry_get_is_default (const MateConfEntry *entry
);
Returns the is_default field of the MateConfEntry , a gboolean value.
gboolean
mateconf_entry_get_is_writable (const MateConfEntry *entry
);
Returns the is_writable field of the MateConfEntry, a gboolean value.
MateConfEntry * mateconf_entry_new (const gchar *key
,const MateConfValue *val
);
Creates a new MateConfEntry with key key
and value val
calling mateconf_entry_new_nocopy()
.
MateConfEntry * mateconf_entry_new_nocopy (gchar *key
,MateConfValue *val
);
Creates a new MateConfEntry 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 MateConfEntry is freed. The string will be freed with
g_free()
so should be allocated with a GLib function, not malloc()
.
MateConfEntry *
mateconf_entry_copy (const MateConfEntry *src
);
Copies the fields of an existing MateConfEntry and returns the new MateConfEntry.
void
mateconf_entry_free (MateConfEntry *entry
);
mateconf_entry_free
is deprecated and should not be used in newly-written code.
Destroys a MateConfEntry, freeing the key, the value, and the entry itself.
MateConfEntry *
mateconf_entry_ref (MateConfEntry *entry
);
Increases the refcount of a MateConfEntry by one.
void
mateconf_entry_unref (MateConfEntry *entry
);
Decreases the refcount of a MateConfEntry by one and frees the MateConfEntry when the refcount becomes zero.
MateConfValue *
mateconf_entry_steal_value (MateConfEntry *entry
);
Extracts the value from a MateConfEntry, leaving the value
field in
MateConfEntry set to NULL. Destroying the MateConfEntry
will not destroy the value; the caller of
mateconf_entry_steal_value()
assumes ownership of it.
void mateconf_entry_set_value (MateConfEntry *entry
,const MateConfValue *val
);
Sets the value field of the MateConfEntry to the MateConfValue passed.
void mateconf_entry_set_value_nocopy (MateConfEntry *entry
,MateConfValue *val
);
Sets the value field to val
after freeing the already existing value.
void mateconf_entry_set_schema_name (MateConfEntry *entry
,const gchar *name
);
Sets the schema_name field of the MateConfEntry to the name passed after freeing the already existing name.
void mateconf_entry_set_is_default (MateConfEntry *entry
,gboolean is_default
);
Sets the is_default field of the MateConfEntry to the boolean value passed.
void mateconf_entry_set_is_writable (MateConfEntry *entry
,gboolean is_writable
);
Sets the is_writable field of the MateConfEntry to the boolean value passed.
Used to indicate the type of a MateConfValue.
Never the type of a MateConfValue obtained from MateConf functions; used to indicate errors and the like. |
||
String value (gchar*). |
||
Integer value (gint). |
||
Floating point value (gdouble). |
||
Boolean value (gboolean). |
||
Schema value (MateConfSchema). |
||
List of MateConfValue; MateConfValue 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. |
||
Pair of MateConfValue; 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 MateConfValue { MateConfValueType type; };
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.
A MateConfValue should always be initialized before use. That is, you should not use a MateConfValue unless you have called one of the functions beginning with "mateconf_value_set_".. For lists, initialization has two steps: first you must set the list element type, then you must set the list value.
MateConfValueType |
The MateConfValueType of this MateConfValue. The only field of MateConfValue you should access directly. |
struct MateConfMetaInfo { gchar* schema; gchar* mod_user; /* user owning the daemon that made the last modification */ GTime mod_time; /* time of the modification */ };
struct MateConfEntry { char *key; MateConfValue *value; };
Stores an entry from a MateConf "directory," including a key-value pair,
the name of the schema applicable to this entry, whether the value is
a default value, and whether MateConf can write a new value at this
key. key
should be an absolute key, not a relative key. (Note that
internally MateConf breaks this rule sometimes; but in the public
interface, key
is always an absolute key.) To access the key and
value, use mateconf_entry_get_key()
and mateconf_entry_get_value()
.
Value can be NULL, indicating that the value is not set.