Xfconf Channel

Xfconf Channel — An application-defined domain for storing configuration settings

Functions

XfconfChannel * xfconf_channel_get ()
XfconfChannel * xfconf_channel_new ()
XfconfChannel * xfconf_channel_new_with_property_base ()
gboolean xfconf_channel_has_property ()
gboolean xfconf_channel_is_property_locked ()
void xfconf_channel_reset_property ()
GHashTable * xfconf_channel_get_properties ()
gchar * xfconf_channel_get_string ()
gchar ** xfconf_channel_get_string_list ()
gint32 xfconf_channel_get_int ()
guint32 xfconf_channel_get_uint ()
guint64 xfconf_channel_get_uint64 ()
gdouble xfconf_channel_get_double ()
gboolean xfconf_channel_get_bool ()
gboolean xfconf_channel_set_string ()
gboolean xfconf_channel_set_string_list ()
gboolean xfconf_channel_set_int ()
gboolean xfconf_channel_set_uint ()
gboolean xfconf_channel_set_uint64 ()
gboolean xfconf_channel_set_double ()
gboolean xfconf_channel_set_bool ()
gboolean xfconf_channel_get_property ()
gboolean xfconf_channel_set_property ()
gboolean xfconf_channel_get_array ()
gboolean xfconf_channel_get_array_valist ()
GPtrArray * xfconf_channel_get_arrayv ()
gboolean xfconf_channel_set_array ()
gboolean xfconf_channel_set_array_valist ()
gboolean xfconf_channel_set_arrayv ()
gboolean xfconf_channel_get_named_struct ()
gboolean xfconf_channel_set_named_struct ()
gboolean xfconf_channel_get_struct ()
gboolean xfconf_channel_get_struct_valist ()
gboolean xfconf_channel_get_structv ()
gboolean xfconf_channel_set_struct ()
gboolean xfconf_channel_set_struct_valist ()
gboolean xfconf_channel_set_structv ()

Properties

char * channel-name Read / Write / Construct Only
gboolean is-singleton Read / Write / Construct Only
char * property-base Read / Write / Construct Only

Signals

void property-changed Has Details

Types and Values

Object Hierarchy

    GObject
    ╰── XfconfChannel

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.

Functions

xfconf_channel_get ()

XfconfChannel *
xfconf_channel_get (const gchar *channel_name);

Either creates a new channel, or fetches a singleton object for channel_name . This function always returns a valid object; no checking is done to see if the channel exists or has a valid name.

The reference count of the returned channel is owned by libxfconf.

Parameters

channel_name

A channel name.

 

Returns

An XfconfChannel singleton.

[transfer none]

Since: 4.5.91


xfconf_channel_new ()

XfconfChannel *
xfconf_channel_new (const gchar *channel_name);

Creates a new channel using name as the channel's identifier. This function always returns a valid object; no checking is done to see if the channel exists or has a valid name.

Note: use of this function is not recommended, in favor of xfconf_channel_get(), which returns a singleton object and saves a little memory. However, xfconf_channel_new() can be useful in some cases where you want to tie an XfconfChannel's lifetime (and thus the lifetime of connected signals and bound GObject properties) to the lifetime of another object.

Also note that each channel has its own cache, so if you create 2 new channels with the same name, it will double the dbus traffic, so in this cases it is highly recommended to use xfconf_channel_get().

Parameters

channel_name

A channel name.

 

Returns

A new XfconfChannel. Release with g_object_unref() when no longer needed.


xfconf_channel_new_with_property_base ()

XfconfChannel *
xfconf_channel_new_with_property_base (const gchar *channel_name,
                                       const gchar *property_base);

Creates a new channel using name as the channel's identifier, restricting the accessible properties to be rooted at property_base . This function always returns a valid object; no checking is done to see if the channel exists or has a valid name.

Parameters

channel_name

A channel name.

 

property_base

A property root name.

 

Returns

A new XfconfChannel. Release with g_object_unref() when no longer needed.

Since: 4.5.92


xfconf_channel_has_property ()

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

Checks to see if property exists on channel .

Parameters

channel

An XfconfChannel.

 

property

A property name.

 

Returns

TRUE if property exists, FALSE otherwise.


xfconf_channel_is_property_locked ()

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

Queries whether or not property on channel is locked by system policy. If the property is locked, calls to xfconf_channel_set_property() (or any of the "set" family of functions) or xfconf_channel_reset_property() will fail.

Parameters

channel

An XfconfChannel.

 

property

A property name.

 

Returns

TRUE if the property is locked, FALSE otherwise.

Since: 4.5.91


xfconf_channel_reset_property ()

void
xfconf_channel_reset_property (XfconfChannel *channel,
                               const gchar *property_base,
                               gboolean recursive);

Resets properties starting at (and including) property_base . If recursive is TRUE, will also reset all properties that are under property_base in the property hierarchy.

A bit of an explanation as to what this function actually does: Since Xfconf backends are expected to support setting defaults via what you might call "optional schema," you can't really "remove" properties. Since the client library can't know if a channel provides default values (or even if the backend supports it!), at best it can only reset properties to their default values.

The property_base parameter can be NULL or the empty string (""), in which case the channel root ("/") will be assumed. Of course, TRUE must be passed for recursive in this case.

Parameters

channel

An XfconfChannel.

 

property_base

A property tree root or property name.

 

recursive

Whether to reset properties recursively.

 

Since: 4.5.91


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 .

Parameters

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.

[element-type utf8 GValue][transfer container]


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 .

Parameters

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 .

Parameters

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.

[transfer full][element-type utf8][array zero-terminated=1]


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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 the value type returned from the configuration store is an array type, each element of the array will be converted to the type of value . If value is uninitialized, the value in the configuration store will be returned in its native type.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

channel

An XfconfChannel.

 

property

A property string.

 

Returns

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

[transfer full][element-type GValue][nullable]


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.

Parameters

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.

Parameters

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.

Parameters

channel

An XfconfChannel.

 

property

A property string.

 

values

A GPtrArray of GValues.

[element-type GValue]

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Types and Values

XfconfChannel

typedef struct _XfconfChannel XfconfChannel;

An opaque structure that holds state about a channel.

Property Details

The “channel-name” property

  “channel-name”             char *

The string identifier used for this channel.

Owner: XfconfChannel

Flags: Read / Write / Construct Only

Default value: NULL


The “is-singleton” property

  “is-singleton”             gboolean

Identifies the instance of the class as a singleton instance or not. This is mainly used internally by XfconfChannel but may be useful for API users.

Owner: XfconfChannel

Flags: Read / Write / Construct Only

Default value: TRUE


The “property-base” property

  “property-base”            char *

The string identifier used for the property base inside a channel. This can be used to restrict a channel to a subset of properties.

Owner: XfconfChannel

Flags: Read / Write / Construct Only

Default value: NULL

Signal Details

The “property-changed” signal

void
user_function (XfconfChannel *channel,
               char          *property,
               GValue        *value,
               gpointer       user_data)

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

1
G_VALUE_TYPE(value) == G_TYPE_INVALID

Parameters

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.

 

Flags: Has Details