Xfconf Channel: xfconf Reference Manual

## 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

| XfconfChannel

## 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 container][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