![]() |
![]() |
![]() |
MateConf Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
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; MateConfValue; #define MATECONF_VALUE_TYPE_VALID (x) const char * mateconf_value_get_string (const MateConfValue *value
); int mateconf_value_get_int (const MateConfValue *value
); double mateconf_value_get_float (const MateConfValue *value
); MateConfValueType mateconf_value_get_list_type (const MateConfValue *value
); GSList * mateconf_value_get_list (const MateConfValue *value
); MateConfValue * mateconf_value_get_car (const MateConfValue *value
); MateConfValue * mateconf_value_get_cdr (const MateConfValue *value
); gboolean mateconf_value_get_bool (const MateConfValue *value
); MateConfSchema * mateconf_value_get_schema (const MateConfValue *value
); MateConfValue * mateconf_value_new (MateConfValueType type
); MateConfValue * mateconf_value_new_from_string (MateConfValueType type
,const gchar *str
,GError **err
); MateConfValue * mateconf_value_copy (const MateConfValue *src
); void mateconf_value_free (MateConfValue *value
); void mateconf_value_set_int (MateConfValue *value
,gint the_int
); void mateconf_value_set_string (MateConfValue *value
,const gchar *the_str
); void mateconf_value_set_float (MateConfValue *value
,gdouble the_float
); void mateconf_value_set_bool (MateConfValue *value
,gboolean the_bool
); void mateconf_value_set_schema (MateConfValue *value
,const MateConfSchema *sc
); void mateconf_value_set_schema_nocopy (MateConfValue *value
,MateConfSchema *sc
); void mateconf_value_set_car (MateConfValue *value
,const MateConfValue *car
); void mateconf_value_set_car_nocopy (MateConfValue *value
,MateConfValue *car
); void mateconf_value_set_cdr (MateConfValue *value
,const MateConfValue *cdr
); void mateconf_value_set_cdr_nocopy (MateConfValue *value
,MateConfValue *cdr
); void mateconf_value_set_list_type (MateConfValue *value
,MateConfValueType type
); void mateconf_value_set_list_nocopy (MateConfValue *value
,GSList *list
); void mateconf_value_set_list (MateConfValue *value
,GSList *list
); gchar * mateconf_value_to_string (const MateConfValue *value
); MateConfMetaInfo; MateConfMetaInfo * mateconf_meta_info_new (void
); void mateconf_meta_info_free (MateConfMetaInfo *gcmi
); const char * mateconf_meta_info_get_schema (MateConfMetaInfo *gcmi
); const char * mateconf_meta_info_get_mod_user (MateConfMetaInfo *gcmi
); GTime mateconf_meta_info_mod_time (MateConfMetaInfo *gcmi
); void mateconf_meta_info_set_schema (MateConfMetaInfo *gcmi
,const gchar *schema_name
); void mateconf_meta_info_set_mod_user (MateConfMetaInfo *gcmi
,const gchar *mod_user
); void mateconf_meta_info_set_mod_time (MateConfMetaInfo *gcmi
,GTime mod_time
); MateConfEntry; const char * mateconf_entry_get_key (const MateConfEntry *entry
); MateConfValue * mateconf_entry_get_value (const MateConfEntry *entry
); const char * mateconf_entry_get_schema_name (const MateConfEntry *entry
); gboolean mateconf_entry_get_is_default (const MateConfEntry *entry
); gboolean mateconf_entry_get_is_writable (const MateConfEntry *entry
); MateConfEntry * mateconf_entry_new (const gchar *key
,const MateConfValue *val
); MateConfEntry * mateconf_entry_new_nocopy (gchar *key
,MateConfValue *val
); MateConfEntry * mateconf_entry_copy (const MateConfEntry *src
); void mateconf_entry_free (MateConfEntry *entry
); MateConfEntry * mateconf_entry_ref (MateConfEntry *entry
); void mateconf_entry_unref (MateConfEntry *entry
); MateConfValue * mateconf_entry_steal_value (MateConfEntry *entry
); void mateconf_entry_set_value (MateConfEntry *entry
,const MateConfValue *val
); void mateconf_entry_set_value_nocopy (MateConfEntry *entry
,MateConfValue *val
); void mateconf_entry_set_schema_name (MateConfEntry *entry
,const gchar *name
); void mateconf_entry_set_is_default (MateConfEntry *entry
,gboolean is_default
); void mateconf_entry_set_is_writable (MateConfEntry *entry
,gboolean is_writable
);
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.)
typedef enum { MATECONF_VALUE_INVALID, MATECONF_VALUE_STRING, MATECONF_VALUE_INT, MATECONF_VALUE_FLOAT, MATECONF_VALUE_BOOL, MATECONF_VALUE_SCHEMA, /* unfortunately these aren't really types; we want list_of_string, list_of_int, etc. but it's just too complicated to implement. instead we'll complain in various places if you do something moronic like mix types in a list or treat pair<string,int> and pair<float,bool> as the same type. */ MATECONF_VALUE_LIST, MATECONF_VALUE_PAIR } MateConfValueType;
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. |
typedef struct { MateConfValueType type; } MateConfValue;
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. |
#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.
|
a MateConfValue. |
Returns : |
a const char*. |
int mateconf_value_get_int (const MateConfValue *value
);
Returns a gint for a MateConfValue with type MATECONF_VALUE_INT
.
|
a MateConfValue. |
Returns : |
a gint. |
double mateconf_value_get_float (const MateConfValue *value
);
Returns a gdouble for a MateConfValue with type MATECONF_VALUE_FLOAT
.
|
a MateConfValue. |
Returns : |
a gdouble. |
MateConfValueType mateconf_value_get_list_type (const MateConfValue *value
);
Returns the type of the list elements in a MateConfValue with type
MATECONF_VALUE_LIST
.
|
a MateConfValue. |
Returns : |
the type of the list elements (a primitive type). |
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.
|
a MateConfValue. |
Returns : |
a GList. [element-type MateConfValue][transfer none MateConfValue] |
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.
|
a MateConfValue. |
Returns : |
the first member of a pair, a primitive type. |
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.
|
a MateConfValue. |
Returns : |
the second member of a pair, a primitive type. |
gboolean mateconf_value_get_bool (const MateConfValue *value
);
Returns a gboolean for a MateConfValue with type MATECONF_VALUE_BOOL
.
|
a MateConfValue. |
Returns : |
a gboolean value. |
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.
|
a MateConfValue. |
Returns : |
a MateConfSchema. |
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.
|
type of the new MateConfValue. |
Returns : |
newly-allocated MateConfValue. |
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 of the new MateConfValue. |
|
the return location for an allocated GError, or NULL to ignore errors. |
|
the value to be set. |
Returns : |
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.
|
a MateConfValue to copy. |
Returns : |
a newly-allocated MateConfValue identical to src .
|
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).
|
a MateConfValue to destroy. |
void mateconf_value_set_int (MateConfValue *value
,gint the_int
);
Sets the value of a MateConfValue with type MATECONF_VALUE_INT
.
|
a MateConfValue of type MATECONF_VALUE_INT .
|
|
the integer. |
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.
|
a MateConfValue of type MATECONF_VALUE_STRING .
|
|
the string. |
void mateconf_value_set_float (MateConfValue *value
,gdouble the_float
);
Sets the value of a MateConfValue with type
MATECONF_VALUE_FLOAT
.
|
a MateConfValue of type MATECONF_VALUE_FLOAT .
|
|
the floating point number. |
void mateconf_value_set_bool (MateConfValue *value
,gboolean the_bool
);
Sets the value of a MateConfValue with type
MATECONF_VALUE_BOOL
.
|
a MateConfValue of type MATECONF_VALUE_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()
.
|
a MateConfValue with type MATECONF_VALUE_SCHEMA .
|
|
the MateConfSchema. |
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()
.
|
a MateConfValue with type MATECONF_VALUE_SCHEMA .
|
|
the MateConfSchema. |
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()
.
|
a MateConfValue with type MATECONF_VALUE_PAIR .
|
|
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()
.
|
a MateConfValue with type MATECONF_VALUE_PAIR .
|
|
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()
.
|
a MateConfValue with type MATECONF_VALUE_PAIR .
|
|
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()
.
|
a MateConfValue with type MATECONF_VALUE_PAIR .
|
|
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.
|
a MateConfValue with type MATECONF_VALUE_LIST .
|
|
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.
|
a MateConfValue with type MATECONF_VALUE_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.
|
a MateConfValue with type MATECONF_VALUE_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()
.
|
a MateConfValue. |
Returns : |
a newly-allocated string representing the MateConfValue. |
typedef struct { gchar* schema; gchar* mod_user; /* user owning the daemon that made the last modification */ GTime mod_time; /* time of the modification */ } MateConfMetaInfo;
MateConfMetaInfo * mateconf_meta_info_new (void
);
Creates a new MateConfMetaInfo structure and returns the newly allocated MateConfMetaInfo.
Returns : |
the newly allocated MateConfMetainfo. |
void mateconf_meta_info_free (MateConfMetaInfo *gcmi
);
Frees the MateConfMetaInfo.
|
the MateConfMetaInfo to be freed. |
const char * mateconf_meta_info_get_schema (MateConfMetaInfo *gcmi
);
Returns the schema field of the MateConfMetaInfo.
|
a MateConfMetaInfo. |
Returns : |
the schema field, a char* value. |
const char * mateconf_meta_info_get_mod_user (MateConfMetaInfo *gcmi
);
Returns the user owning the daemon that made the last modification of the key.
|
a MateConfMetaInfo. |
Returns : |
mod_user, a char* value. |
GTime mateconf_meta_info_mod_time (MateConfMetaInfo *gcmi
);
Returns the last modification time of the key.
|
a MateConfMetaInfo. |
Returns : |
the mod_time, a GTime value. |
void mateconf_meta_info_set_schema (MateConfMetaInfo *gcmi
,const gchar *schema_name
);
Sets the schema_name field of the MateConfMetaInfo to the name passed.
|
a MateConfMetaInfo. |
|
the name to be set for the schema, a gchar* value. |
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.
|
a MateConfMetaInfo. |
|
the value to be set, a char*. |
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.
|
a MateConfMetaInfo. |
|
a GTime. |
typedef struct { char *key; MateConfValue *value; } MateConfEntry;
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.
an absolute key name. | |
MateConfValue * |
the value. |
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.
|
a MateConfEntry. |
Returns : |
the key , a char*. |
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.
|
a MateConfEntry. |
Returns : |
a MateConfValue. |
const char * mateconf_entry_get_schema_name (const MateConfEntry *entry
);
Returns the schema_name field of the MateConfEntry.
|
a MateConfEntry. |
Returns : |
the schema_name , a char* value. |
gboolean mateconf_entry_get_is_default (const MateConfEntry *entry
);
Returns the is_default field of the MateConfEntry , a gboolean value.
|
a MateConfEntry. |
Returns : |
a gboolean value. |
gboolean mateconf_entry_get_is_writable (const MateConfEntry *entry
);
Returns the is_writable field of the MateConfEntry, a gboolean value.
|
a MateConfEntry. |
Returns : |
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()
.
|
the key name. |
|
the value. |
Returns : |
a new MateConfEntry. |
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()
.
|
the key name. |
|
the value. |
Returns : |
a new MateConfEntry. |
MateConfEntry * mateconf_entry_copy (const MateConfEntry *src
);
Copies the fields of an existing MateConfEntry and returns the new MateConfEntry.
|
the MateConfEntry to be copied. |
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.
|
a MateConfEntry to free. |
MateConfEntry * mateconf_entry_ref (MateConfEntry *entry
);
Increases the refcount of a MateConfEntry by one.
|
a MateConfEntry. |
Returns : |
the referenced MateConfEntry. |
void mateconf_entry_unref (MateConfEntry *entry
);
Decreases the refcount of a MateConfEntry by one and frees the MateConfEntry when the refcount becomes zero.
|
a MateConfEntry. |
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.
|
a MateConfEntry. |
Returns : |
a MateConfValue that the caller must free. |
void mateconf_entry_set_value (MateConfEntry *entry
,const MateConfValue *val
);
Sets the value field of the MateConfEntry to the MateConfValue passed.
|
a MateConfEntry. |
|
a MateConfValue. |
void mateconf_entry_set_value_nocopy (MateConfEntry *entry
,MateConfValue *val
);
Sets the value field to val
after freeing the already existing value.
|
a MateConfEntry. |
|
the MateConfValue to be set. |
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.
|
a MateConfEntry. |
|
the name to be set for the schema, a gchar* value. |
void mateconf_entry_set_is_default (MateConfEntry *entry
,gboolean is_default
);
Sets the is_default field of the MateConfEntry to the boolean value passed.
|
a MateConfEntry. |
|
the boolean value to be set. |
void mateconf_entry_set_is_writable (MateConfEntry *entry
,gboolean is_writable
);
Sets the is_writable field of the MateConfEntry to the boolean value passed.
|
a MateConfEntry. |
|
a boolean value. |