MateConfValue, MateConfEntry, MateConfMetaInfo

MateConfValue, MateConfEntry, MateConfMetaInfo — A MateConfValue stores a dynamically-typed value. A MateConfEntry stores a key-value pair. A MateConfMetaInfo stores metainformation about a key.

Functions

#define MATECONF_VALUE_TYPE_VALID()
const char * mateconf_value_get_string ()
int mateconf_value_get_int ()
double mateconf_value_get_float ()
MateConfValueType mateconf_value_get_list_type ()
GSList * mateconf_value_get_list ()
MateConfValue * mateconf_value_get_car ()
MateConfValue * mateconf_value_get_cdr ()
gboolean mateconf_value_get_bool ()
MateConfSchema * mateconf_value_get_schema ()
MateConfValue * mateconf_value_new ()
MateConfValue * mateconf_value_new_from_string ()
MateConfValue * mateconf_value_copy ()
void mateconf_value_free ()
void mateconf_value_set_int ()
void mateconf_value_set_string ()
void mateconf_value_set_float ()
void mateconf_value_set_bool ()
void mateconf_value_set_schema ()
void mateconf_value_set_schema_nocopy ()
void mateconf_value_set_car ()
void mateconf_value_set_car_nocopy ()
void mateconf_value_set_cdr ()
void mateconf_value_set_cdr_nocopy ()
void mateconf_value_set_list_type ()
void mateconf_value_set_list_nocopy ()
void mateconf_value_set_list ()
gchar * mateconf_value_to_string ()
MateConfMetaInfo * mateconf_meta_info_new ()
void mateconf_meta_info_free ()
const char * mateconf_meta_info_get_schema ()
const char * mateconf_meta_info_get_mod_user ()
GTime mateconf_meta_info_mod_time ()
void mateconf_meta_info_set_schema ()
void mateconf_meta_info_set_mod_user ()
void mateconf_meta_info_set_mod_time ()
const char * mateconf_entry_get_key ()
MateConfValue * mateconf_entry_get_value ()
const char * mateconf_entry_get_schema_name ()
gboolean mateconf_entry_get_is_default ()
gboolean mateconf_entry_get_is_writable ()
MateConfEntry * mateconf_entry_new ()
MateConfEntry * mateconf_entry_new_nocopy ()
MateConfEntry * mateconf_entry_copy ()
void mateconf_entry_free ()
MateConfEntry * mateconf_entry_ref ()
void mateconf_entry_unref ()
MateConfValue * mateconf_entry_steal_value ()
void mateconf_entry_set_value ()
void mateconf_entry_set_value_nocopy ()
void mateconf_entry_set_schema_name ()
void mateconf_entry_set_is_default ()
void mateconf_entry_set_is_writable ()

Types and Values

Description

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.)

Functions

MATECONF_VALUE_TYPE_VALID()

#define MATECONF_VALUE_TYPE_VALID(x) (((x) > MATECONF_VALUE_INVALID) && ((x) <= MATECONF_VALUE_PAIR))


mateconf_value_get_string ()

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.

Parameters

value

a MateConfValue.

 

Returns

a const char*.


mateconf_value_get_int ()

int
mateconf_value_get_int (const MateConfValue *value);

Returns a gint for a MateConfValue with type MATECONF_VALUE_INT.

Parameters

value

a MateConfValue.

 

Returns

a gint.


mateconf_value_get_float ()

double
mateconf_value_get_float (const MateConfValue *value);

Returns a gdouble for a MateConfValue with type MATECONF_VALUE_FLOAT.

Parameters

value

a MateConfValue.

 

Returns

a gdouble.


mateconf_value_get_list_type ()

MateConfValueType
mateconf_value_get_list_type (const MateConfValue *value);

Returns the type of the list elements in a MateConfValue with type MATECONF_VALUE_LIST.

Parameters

value

a MateConfValue.

 

Returns

the type of the list elements (a primitive type).


mateconf_value_get_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

NULL. The list is not a copy; it is "owned" by the

MateConfValue and will be destroyed when the MateConfValue is destroyed.

Parameters

value

a MateConfValue.

 

Returns

a GList.

[element-type MateConfValue][transfer none]


mateconf_value_get_car ()

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.

Parameters

value

a MateConfValue.

 

Returns

the first member of a pair, a primitive type.


mateconf_value_get_cdr ()

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.

Parameters

value

a MateConfValue.

 

Returns

the second member of a pair, a primitive type.


mateconf_value_get_bool ()

gboolean
mateconf_value_get_bool (const MateConfValue *value);

Returns a gboolean for a MateConfValue with type MATECONF_VALUE_BOOL.

Parameters

value

a MateConfValue.

 

Returns

a gboolean value.


mateconf_value_get_schema ()

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.

Parameters

value

a MateConfValue.

 

Returns

a MateConfSchema.


mateconf_value_new ()

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.

Parameters

type

type of the new MateConfValue.

 

Returns

newly-allocated MateConfValue.


mateconf_value_new_from_string ()

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.

Parameters

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.

 

Returns

the value to be set.


mateconf_value_copy ()

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.

Parameters

src

a MateConfValue to copy.

 

Returns

a newly-allocated MateConfValue identical to src .


mateconf_value_free ()

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).

Parameters

value

a MateConfValue to destroy.

 

mateconf_value_set_int ()

void
mateconf_value_set_int (MateConfValue *value,
                        gint the_int);

Sets the value of a MateConfValue with type MATECONF_VALUE_INT.

Parameters

value

a MateConfValue of type MATECONF_VALUE_INT.

 

the_int

the integer.

 

mateconf_value_set_string ()

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.

Parameters

value

a MateConfValue of type MATECONF_VALUE_STRING.

 

the_str

the string.

 

mateconf_value_set_float ()

void
mateconf_value_set_float (MateConfValue *value,
                          gdouble the_float);

Sets the value of a MateConfValue with type MATECONF_VALUE_FLOAT.

Parameters

value

a MateConfValue of type MATECONF_VALUE_FLOAT.

 

the_float

the floating point number.

 

mateconf_value_set_bool ()

void
mateconf_value_set_bool (MateConfValue *value,
                         gboolean the_bool);

Sets the value of a MateConfValue with type MATECONF_VALUE_BOOL.

Parameters

value

a MateConfValue of type MATECONF_VALUE_BOOL.

 

the_bool

a boolean value (TRUE or FALSE).

 

mateconf_value_set_schema ()

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().

Parameters

value

a MateConfValue with type MATECONF_VALUE_SCHEMA.

 

sc

the MateConfSchema.

 

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().

Parameters

value

a MateConfValue with type MATECONF_VALUE_SCHEMA.

 

sc

the MateConfSchema.

 

mateconf_value_set_car ()

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().

Parameters

value

a MateConfValue with type MATECONF_VALUE_PAIR.

 

car

the MateConfValue to set as the car of the pair.

 

mateconf_value_set_car_nocopy ()

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().

Parameters

value

a MateConfValue with type MATECONF_VALUE_PAIR.

 

car

the MateConfValue to set as the car of the pair.

 

mateconf_value_set_cdr ()

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().

Parameters

value

a MateConfValue with type MATECONF_VALUE_PAIR.

 

cdr

the MateConfValue to set as the cdr of the pair.

 

mateconf_value_set_cdr_nocopy ()

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().

Parameters

value

a MateConfValue with type MATECONF_VALUE_PAIR.

 

cdr

the MateConfValue to set as the cdr of the pair.

 

mateconf_value_set_list_type ()

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.

Parameters

value

a MateConfValue with type MATECONF_VALUE_LIST.

 

type

the type of elements in this list.

 

mateconf_value_set_list_nocopy ()

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.

Parameters

value

a MateConfValue with type MATECONF_VALUE_LIST.

 

list

the GSList of MateConfValue to set as the list value.

 

mateconf_value_set_list ()

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.

Parameters

value

a MateConfValue with type MATECONF_VALUE_LIST.

 

list

the GSList of MateConfValue to set as the list value.

 

mateconf_value_to_string ()

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().

Parameters

value

a MateConfValue.

 

Returns

a newly-allocated string representing the MateConfValue.


mateconf_meta_info_new ()

MateConfMetaInfo *
mateconf_meta_info_new (void);

Creates a new MateConfMetaInfo structure and returns the newly allocated MateConfMetaInfo.

Returns

the newly allocated MateConfMetainfo.


mateconf_meta_info_free ()

void
mateconf_meta_info_free (MateConfMetaInfo *gcmi);

Frees the MateConfMetaInfo.

Parameters

gcmi

the MateConfMetaInfo to be freed.

 

mateconf_meta_info_get_schema ()

const char *
mateconf_meta_info_get_schema (MateConfMetaInfo *gcmi);

Returns the schema field of the MateConfMetaInfo.

Parameters

gcmi

a MateConfMetaInfo.

 

Returns

the schema field, a char* value.


mateconf_meta_info_get_mod_user ()

const char *
mateconf_meta_info_get_mod_user (MateConfMetaInfo *gcmi);

Returns the user owning the daemon that made the last modification of the key.

Parameters

gcmi

a MateConfMetaInfo.

 

Returns

mod_user, a char* value.


mateconf_meta_info_mod_time ()

GTime
mateconf_meta_info_mod_time (MateConfMetaInfo *gcmi);

Returns the last modification time of the key.

Parameters

gcmi

a MateConfMetaInfo.

 

Returns

the mod_time, a GTime value.


mateconf_meta_info_set_schema ()

void
mateconf_meta_info_set_schema (MateConfMetaInfo *gcmi,
                               const gchar *schema_name);

Sets the schema_name field of the MateConfMetaInfo to the name passed.

Parameters

gcmi

a MateConfMetaInfo.

 

schema_name

the name to be set for the schema, a gchar* value.

 

mateconf_meta_info_set_mod_user ()

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.

Parameters

gcmi

a MateConfMetaInfo.

 

mod_user

the value to be set, a char*.

 

mateconf_meta_info_set_mod_time ()

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.

Parameters

gcmi

a MateConfMetaInfo.

 

mod_time

a GTime.

 

mateconf_entry_get_key ()

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.

Parameters

entry

a MateConfEntry.

 

Returns

the key , a char*.


mateconf_entry_get_value ()

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.

Parameters

entry

a MateConfEntry.

 

Returns

a MateConfValue.


mateconf_entry_get_schema_name ()

const char *
mateconf_entry_get_schema_name (const MateConfEntry *entry);

Returns the schema_name field of the MateConfEntry.

Parameters

entry

a MateConfEntry.

 

Returns

the schema_name , a char* value.


mateconf_entry_get_is_default ()

gboolean
mateconf_entry_get_is_default (const MateConfEntry *entry);

Returns the is_default field of the MateConfEntry , a gboolean value.

Parameters

entry

a MateConfEntry.

 

Returns

a gboolean value.


mateconf_entry_get_is_writable ()

gboolean
mateconf_entry_get_is_writable (const MateConfEntry *entry);

Returns the is_writable field of the MateConfEntry, a gboolean value.

Parameters

entry

a MateConfEntry.

 

Returns

a gboolean value.


mateconf_entry_new ()

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().

Parameters

key

the key name.

 

val

the value.

 

Returns

a new MateConfEntry.


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().

Parameters

key

the key name.

 

val

the value.

 

Returns

a new MateConfEntry.


mateconf_entry_copy ()

MateConfEntry *
mateconf_entry_copy (const MateConfEntry *src);

Copies the fields of an existing MateConfEntry and returns the new MateConfEntry.

Parameters

src

the MateConfEntry to be copied.

 

Returns

the new MateConfEntry.


mateconf_entry_free ()

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.

Parameters

entry

a MateConfEntry to free.

 

mateconf_entry_ref ()

MateConfEntry *
mateconf_entry_ref (MateConfEntry *entry);

Increases the refcount of a MateConfEntry by one.

Parameters

entry

a MateConfEntry.

 

Returns

the referenced MateConfEntry.


mateconf_entry_unref ()

void
mateconf_entry_unref (MateConfEntry *entry);

Decreases the refcount of a MateConfEntry by one and frees the MateConfEntry when the refcount becomes zero.

Parameters

entry

a MateConfEntry.

 

mateconf_entry_steal_value ()

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.

Parameters

entry

a MateConfEntry.

 

Returns

a MateConfValue that the caller must free.


mateconf_entry_set_value ()

void
mateconf_entry_set_value (MateConfEntry *entry,
                          const MateConfValue *val);

Sets the value field of the MateConfEntry to the MateConfValue passed.

Parameters

entry

a MateConfEntry.

 

val

a MateConfValue.

 

mateconf_entry_set_value_nocopy ()

void
mateconf_entry_set_value_nocopy (MateConfEntry *entry,
                                 MateConfValue *val);

Sets the value field to val after freeing the already existing value.

Parameters

entry

a MateConfEntry.

 

val

the MateConfValue to be set.

 

mateconf_entry_set_schema_name ()

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.

Parameters

entry

a MateConfEntry.

 

name

the name to be set for the schema, a gchar* value.

 

mateconf_entry_set_is_default ()

void
mateconf_entry_set_is_default (MateConfEntry *entry,
                               gboolean is_default);

Sets the is_default field of the MateConfEntry to the boolean value passed.

Parameters

entry

a MateConfEntry.

 

is_default

the boolean value to be set.

 

mateconf_entry_set_is_writable ()

void
mateconf_entry_set_is_writable (MateConfEntry *entry,
                                gboolean is_writable);

Sets the is_writable field of the MateConfEntry to the boolean value passed.

Parameters

entry

a MateConfEntry.

 

is_writable

a boolean value.

 

Types and Values

enum MateConfValueType

Used to indicate the type of a MateConfValue.

Members

MATECONF_VALUE_INVALID

Never the type of a MateConfValue obtained from MateConf functions; used to indicate errors and the like.

 

MATECONF_VALUE_STRING

String value (gchar*).

 

MATECONF_VALUE_INT

Integer value (gint).

 

MATECONF_VALUE_FLOAT

Floating point value (gdouble).

 

MATECONF_VALUE_BOOL

Boolean value (gboolean).

 

MATECONF_VALUE_SCHEMA

Schema value (MateConfSchema).

 

MATECONF_VALUE_LIST

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.

 

MATECONF_VALUE_PAIR

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

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.

Members

MateConfValueType type;

The MateConfValueType of this MateConfValue. The only field of MateConfValue you should access directly.

 

struct MateConfMetaInfo

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

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.

Members

char *key;

an absolute key name.

 

MateConfValue *value;

the value.