XfconfChannel

XfconfChannel — An application-defined domain for storing configuration settings

Synopsis

                    XfconfChannel;
XfconfChannel*      xfconf_channel_new                  (const gchar *channel_name);
gboolean            xfconf_channel_has_property         (XfconfChannel *channel,
                                                         const gchar *property);
void                xfconf_channel_remove_property      (XfconfChannel *channel,
                                                         const gchar *property);
void                xfconf_channel_remove_properties    (XfconfChannel *channel,
                                                         const gchar *property_base);
GHashTable*         xfconf_channel_get_properties       (XfconfChannel *channel,
                                                         const gchar *property_base);
gchar*              xfconf_channel_get_string           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *default_value);
gchar**             xfconf_channel_get_string_list      (XfconfChannel *channel,
                                                         const gchar *property);
gint32              xfconf_channel_get_int              (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gint32 default_value);
guint32             xfconf_channel_get_uint             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint32 default_value);
guint64             xfconf_channel_get_uint64           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint64 default_value);
gdouble             xfconf_channel_get_double           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gdouble default_value);
gboolean            xfconf_channel_get_bool             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gboolean default_value);
gboolean            xfconf_channel_set_string           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *value);
gboolean            xfconf_channel_set_string_list      (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar * const *values);
gboolean            xfconf_channel_set_int              (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gint32 value);
gboolean            xfconf_channel_set_uint             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint32 value);
gboolean            xfconf_channel_set_uint64           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint64 value);
gboolean            xfconf_channel_set_double           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gdouble value);
gboolean            xfconf_channel_set_bool             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gboolean value);
gboolean            xfconf_channel_get_property         (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GValue *value);
gboolean            xfconf_channel_set_property         (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const GValue *value);
gboolean            xfconf_channel_get_array            (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         ...);
gboolean            xfconf_channel_get_array_valist     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         va_list var_args);
GPtrArray*          xfconf_channel_get_arrayv           (XfconfChannel *channel,
                                                         const gchar *property);
gboolean            xfconf_channel_set_array            (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         ...);
gboolean            xfconf_channel_set_array_valist     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         va_list var_args);
gboolean            xfconf_channel_set_arrayv           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GPtrArray *values);
gboolean            xfconf_channel_get_named_struct     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *struct_name,
                                                         gpointer value_struct);
gboolean            xfconf_channel_set_named_struct     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *struct_name,
                                                         gpointer value_struct);
gboolean            xfconf_channel_get_struct           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         GType first_member_type,
                                                         ...);
gboolean            xfconf_channel_get_struct_valist    (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         GType first_member_type,
                                                         va_list var_args);
gboolean            xfconf_channel_get_structv          (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         guint n_members,
                                                         GType *member_types);
gboolean            xfconf_channel_set_struct           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         GType first_member_type,
                                                         ...);
gboolean            xfconf_channel_set_struct_valist    (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         GType first_member_type,
                                                         va_list var_args);
gboolean            xfconf_channel_set_structv          (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         guint n_members,
                                                         GType *member_types);

Object Hierarchy

  GObject
   +----XfconfChannel

Properties

  "channel-name"             gchar*                : Read / Write / Construct Only

Signals

  "property-changed"                               : Run Last / Has Details

Description

An XfconfChannel is a representation of a restricted domain or namespace that an application can define to store configuration settings. This is to ensure that different applications do not store configuration keys with the same names.

Details

XfconfChannel

typedef struct _XfconfChannel XfconfChannel;

An opaque structure that holds state about a channel.


xfconf_channel_new ()

XfconfChannel*      xfconf_channel_new                  (const gchar *channel_name);

Creates a new channel using name as the channel's identifier. Note that this function does no checking to see if the channel exists or is new.

channel_name :

A channel name.

Returns :

A new XfconfChannel.

xfconf_channel_has_property ()

gboolean            xfconf_channel_has_property         (XfconfChannel *channel,
                                                         const gchar *property);

Checks to see if property exists on channel.

channel :

An XfconfChannel.

property :

A property name.

Returns :

TRUE if property exists, FALSE otherwise.

xfconf_channel_remove_property ()

void                xfconf_channel_remove_property      (XfconfChannel *channel,
                                                         const gchar *property);

Removes property from channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

xfconf_channel_remove_properties ()

void                xfconf_channel_remove_properties    (XfconfChannel *channel,
                                                         const gchar *property_base);

Removes property_base from channel, and removes all sub-properties of property_base as well. To remove the entire channel, specify "/" or NULL for property_base.

channel :

An XfconfChannel.

property_base :

The base property name of properties to remove.

xfconf_channel_get_properties ()

GHashTable*         xfconf_channel_get_properties       (XfconfChannel *channel,
                                                         const gchar *property_base);

Retrieves multiple properties from channel and stores them in a GHashTable in which the keys correspond to the string (gchar *) property names, and the values correspond to variant (GValue *) values. The keys and values are owned by the hash table and should be copied if needed. The value of the property specified by property_base (if it exists) and all sub-properties are retrieved. To retrieve all properties in the channel, specify "/" or NULL for property_base.

channel :

An XfconfChannel.

property_base :

The base property name of properties to retrieve.

Returns :

A newly-allocated GHashTable, which should be freed with g_hash_table_destroy() when no longer needed.

xfconf_channel_get_string ()

gchar*              xfconf_channel_get_string           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *default_value);

Retrieves the string value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

default_value :

A fallback value.

Returns :

A newly-allocated string which should be freed with g_free() when no longer needed. If property is not in channel, a g_strdup()ed copy of default_value is returned.

xfconf_channel_get_string_list ()

gchar**             xfconf_channel_get_string_list      (XfconfChannel *channel,
                                                         const gchar *property);

Retrieves the string list value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

Returns :

A newly-allocated string list which should be freed with g_strfreev() when no longer needed. If property is not in channel, NULL is returned.

xfconf_channel_get_int ()

gint32              xfconf_channel_get_int              (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gint32 default_value);

Retrieves the int value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

default_value :

A fallback value.

Returns :

The int value, or, if property is not in channel, default_value is returned.

xfconf_channel_get_uint ()

guint32             xfconf_channel_get_uint             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint32 default_value);

Retrieves the unsigned int value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

default_value :

A fallback value.

Returns :

The uint value, or, if property is not in channel, default_value is returned.

xfconf_channel_get_uint64 ()

guint64             xfconf_channel_get_uint64           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint64 default_value);

Retrieves the 64-bit int value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

default_value :

A fallback value.

Returns :

The uint64 value, or, if property is not in channel, default_value is returned.

xfconf_channel_get_double ()

gdouble             xfconf_channel_get_double           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gdouble default_value);

Retrieves the double value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

default_value :

A fallback value.

Returns :

The double value, or, if property is not in channel, default_value is returned.

xfconf_channel_get_bool ()

gboolean            xfconf_channel_get_bool             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gboolean default_value);

Retrieves the boolean value associated with property on channel.

channel :

An XfconfChannel.

property :

A property name.

default_value :

A fallback value.

Returns :

The boolean value, or, if property is not in channel, default_value is returned.

xfconf_channel_set_string ()

gboolean            xfconf_channel_set_string           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *value);

Sets value for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

value :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_set_string_list ()

gboolean            xfconf_channel_set_string_list      (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar * const *values);

Sets values for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

values :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_set_int ()

gboolean            xfconf_channel_set_int              (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gint32 value);

Sets value for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

value :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_set_uint ()

gboolean            xfconf_channel_set_uint             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint32 value);

Sets value for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

value :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_set_uint64 ()

gboolean            xfconf_channel_set_uint64           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint64 value);

Sets value for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

value :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_set_double ()

gboolean            xfconf_channel_set_double           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gdouble value);

Sets value for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

value :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_set_bool ()

gboolean            xfconf_channel_set_bool             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gboolean value);

Sets value for property on channel in the configuration store.

channel :

An XfconfChannel.

property :

A property name.

value :

The value to set.

Returns :

TRUE on success, FALSE if an error occured.

xfconf_channel_get_property ()

gboolean            xfconf_channel_get_property         (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GValue *value);

Gets a property on channel and stores it in value. The caller is responsible for calling g_value_unset() when finished with value.

This function can be called with an initialized or uninitialized value. If value is initialized to a particular type, libxfconf will attempt to convert the value returned from the configuration store to that type if they don't match. If value is uninitialized, The value in the configuration store will be returned in its native type.

channel :

An XfconfChannel.

property :

A string property name.

value :

A GValue.

Returns :

TRUE if the property was retrieved successfully, FALSE otherwise.

xfconf_channel_set_property ()

gboolean            xfconf_channel_set_property         (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const GValue *value);

Sets the value stored in value to a property on channel.

Note: The configuration store backend almost certainly supports only a restricted set of value types.

channel :

An XfconfChannel.

property :

A string property name.

value :

A GValue.

Returns :

TRUE if the property was set successfully, FALSE otherwise.

xfconf_channel_get_array ()

gboolean            xfconf_channel_get_array            (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         ...);

Gets an array property on channel. The first_value_type argument specifies the type of the first value in the variable argument list. The variable argument list should alternate between pointers to locations to store the values, and the GType of the next value. The argument list should be terminated with G_TYPE_INVALID.

Note: The configuration store backend almost certainly supports only a restricted set of value types.

channel :

An XfconfChannel.

property :

A property string.

first_value_type :

The type of the first argument in the array.

... :

A variable argument list of types and values.

Returns :

TRUE if the property was retrieved successfully, FALSE otherwise.

xfconf_channel_get_array_valist ()

gboolean            xfconf_channel_get_array_valist     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         va_list var_args);

Gets an array property on channel. See xfconf_channel_get_array() for details.

channel :

An XfconfChannel.

property :

A property string.

first_value_type :

The type of the first argument in the array.

var_args :

A variable argument list of types and values.

Returns :

TRUE if the property was retrieved successfully, FALSE otherwise.

xfconf_channel_get_arrayv ()

GPtrArray*          xfconf_channel_get_arrayv           (XfconfChannel *channel,
                                                         const gchar *property);

Gets an array property on channel and returns it as a GPtrArray, which can be freed with xfconf_array_free() when no longer needed.

channel :

An XfconfChannel.

property :

A property string.

Returns :

A newly-allocated GPtrArray on success, or NULL on failure.

xfconf_channel_set_array ()

gboolean            xfconf_channel_set_array            (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         ...);

Sets an array property on channel. The first_value_type argument specifies the type of the first value in the variable argument list. Note that all values specified MUST be pointers to variables holding the correct value, and may not be, e.g., numeric constants. The argument list should be terminated with G_TYPE_INVALID.

Note: The configuration store backend almost certainly supports only a restricted set of value types.

channel :

An XfconfChannel.

property :

A property string.

first_value_type :

The type of the first argument in the array.

... :

A variable argument list of types and values.

Returns :

TRUE if the property was set successfully, FALSE otherwise.

xfconf_channel_set_array_valist ()

gboolean            xfconf_channel_set_array_valist     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         va_list var_args);

Sets an array property on channel. See xfconf_channel_set_array() for details.

channel :

An XfconfChannel.

property :

A property string.

first_value_type :

The type of the first argument in the array.

var_args :

A variable argument list of types and values.

Returns :

TRUE if the property was set successfully, FALSE otherwise.

xfconf_channel_set_arrayv ()

gboolean            xfconf_channel_set_arrayv           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GPtrArray *values);

Sets an array property on channel, using the values in the provided values array.

channel :

An XfconfChannel.

property :

A property string.

values :

A GPtrArray of GValues.

Returns :

TRUE if the property was set successfully, FALSE otherwise.

xfconf_channel_get_named_struct ()

gboolean            xfconf_channel_get_named_struct     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *struct_name,
                                                         gpointer value_struct);

Gets a property from channel and fills in value_struct using the retrieved values. The struct_name parameter is the same name that must have been used to register the struct's layout with xfconf_named_struct_register().

channel :

An XfconfChannel.

property :

A string property name.

struct_name :

A string struct name.

value_struct :

A pointer to a struct.

Returns :

TRUE if the property was retrieved successfully, FALSE otherwise.

xfconf_channel_set_named_struct ()

gboolean            xfconf_channel_set_named_struct     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *struct_name,
                                                         gpointer value_struct);

Sets a property on channel using the members of value_struct as the array of values. The struct_name parameter is the same name that must have been used to register the struct's layout with xfconf_named_struct_register().

channel :

An XfconfChannel.

property :

A string property name.

struct_name :

A string struct name.

value_struct :

A pointer to a struct.

Returns :

TRUE if the property was set successfully, FALSE otherwise.

xfconf_channel_get_struct ()

gboolean            xfconf_channel_get_struct           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         GType first_member_type,
                                                         ...);

Gets a property on channel and stores it as members of the value_struct struct. The first_member_type argument specifies the GType of the first member of the struct. The variable argument list specifies the GTypes of the rest of the struct members, and should be terminated with G_TYPE_INVALID.

Note: This function takes your compiler's and platform's struct member alignment rules into account when storing values in value_struct. Therefore, it cannot be used with structs that are declared as "packed" in such a way that the alignment rules are ignored by the compiler.

Note: Struct members can only be non-pointer types such as int, boolean, double, etc.

channel :

An XfconfChannel.

property :

A string property name.

value_struct :

A pointer to a struct in which to store values.

first_member_type :

The GType of the first member of value_struct.

... :

A variable argument list of GTypes.

Returns :

TRUE if the property was retrieved successfully, FALSE oherwise.

xfconf_channel_get_struct_valist ()

gboolean            xfconf_channel_get_struct_valist    (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         GType first_member_type,
                                                         va_list var_args);

Gets a property on channel and stores it as members of the value_struct struct. See xfconf_channel_get_struct() for details.

Note: Struct members can only be non-pointer types such as int, boolean, double, etc.

channel :

An XfconfChannel.

property :

A string property name.

value_struct :

A pointer to a struct in which to store values.

first_member_type :

The GType of the first member of value_struct.

var_args :

A variable argument list of GTypes.

Returns :

TRUE if the property was retrieved successfully, FALSE oherwise.

xfconf_channel_get_structv ()

gboolean            xfconf_channel_get_structv          (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         guint n_members,
                                                         GType *member_types);

Gets a property on channel and stores it as members of the value_struct struct. The member_types array should hold a GType for each member of the struct.

Note: Struct members can only be non-pointer types such as int, boolean, double, etc.

channel :

An XfconfChannel.

property :

A string property name.

value_struct :

A pointer to a struct in which to store values.

n_members :

The number of data members in the struct.

member_types :

An array of n_members GTypes.

Returns :

TRUE if the property was retrieved successfully, FALSE oherwise.

xfconf_channel_set_struct ()

gboolean            xfconf_channel_set_struct           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         GType first_member_type,
                                                         ...);

Sets a property on channel using the members of value_struct as a value array. The first_member_type argument specifies the GType of the first member of the struct. The variable argument list specifies the GTypes of the rest of the struct members, and should be terminated with G_TYPE_INVALID.

Note: This function takes your compiler's and platform's struct member alignment rules into account when taking values in value_struct. Therefore, it cannot be used with structs that are declared as "packed" such that the alignment rules are ignored by the compiler.

channel :

An XfconfChannel.

property :

A string property name.

value_struct :

A pointer to a struct from which to take values.

first_member_type :

The GType of the first member of value_struct.

... :

A variable argument list of GTypes.

Returns :

TRUE if the property was set successfully, FALSE oherwise.

xfconf_channel_set_struct_valist ()

gboolean            xfconf_channel_set_struct_valist    (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         GType first_member_type,
                                                         va_list var_args);

Sets a property on channel using the members of value_struct as a value array. See xfconf_channel_set_struct() for details.

channel :

An XfconfChannel.

property :

A string property name.

value_struct :

A pointer to a struct from which to take values.

first_member_type :

The GType of the first member of value_struct.

var_args :

A variable argument list of GTypes.

Returns :

TRUE if the property was set successfully, FALSE oherwise.

xfconf_channel_set_structv ()

gboolean            xfconf_channel_set_structv          (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         guint n_members,
                                                         GType *member_types);

Sets a property on channel using the members of value_struct as a value array. The member_types array should hold a GType for each member of the struct.

channel :

An XfconfChannel.

property :

A string property name.

value_struct :

A pointer to a struct from which to take values.

n_members :

The number of data members in the struct.

member_types :

An array of n_members GTypes.

Returns :

TRUE if the property was set successfully, FALSE oherwise.

Property Details

The "channel-name" property

  "channel-name"             gchar*                : Read / Write / Construct Only

The name of the channel.

Default value: NULL

Signal Details

The "property-changed" signal

void                user_function                      (XfconfChannel *channel,
                                                        gchar         *property,
                                                        GValue        *value,
                                                        gpointer       user_data)      : Run Last / Has Details

Emitted whenever a property on channel has changed. If the change was caused by the removal of property, value will be unset; you should test this with

G_VALUE_TYPE(value) == G_TYPE_INVALID

channel :

The XfconfChannel emitting the signal.

property :

The property that changed.

value :

The new value.

user_data :

user data set when the signal handler was connected.