Resource Config File Support

Resource Config File Support — functions for reading and writing resource config files.

Functions

Types and Values

  XfceRc

Includes

#include <libxfce4util/libxfce4util.h>

Description

Provides support for parsing INI-style resource config files like used by for example KDE and some Xfce components (like xfwm4, who uses rc files for the themes).

The parser itself is optimized for high-performance using memory and string chunks to reduce the time spent looking for heap memory (a nice side effect of this is the reduced heap corruption). But due to this fact, an XfceRc object might consume quite a lot of memory after some time of usage. Therefore you should close an XfceRc object as soon as possible after loading configuration data from the object.

Functions

xfce_rc_simple_open ()

XfceRc *
xfce_rc_simple_open (const gchar *filename,
                     gboolean readonly);

Parses the resource config file specified by filename .

If readonly is TRUE parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass TRUE for readonly , xfce_rc_simple_open will fail if filename does not reference a regular file.

It is no error if readonly is FALSE and the file referenced by filename does not exists. In this case you'll start with a fresh config, which contains only the default group and no entries.

Parameters

filename

name of the filename to open.

 

readonly

whether to open filename readonly.

 

Returns

the newly created XfceRc object, or NULL on error.

[transfer full]

Since: 4.2


xfce_rc_config_open ()

XfceRc *
xfce_rc_config_open (XfceResourceType type,
                     const gchar *resource,
                     gboolean readonly);

If readonly is TRUE parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass TRUE for readonly , xfce_rc_config will fail if resource does not reference a regular file.

It is no error if readonly is FALSE and the file referenced by resource does not exists. In this case you'll start with a fresh config, which contains only the default group and no entries.

Parameters

type

The resource type being opened

 

resource

The resource name to open

 

readonly

whether to open resource readonly.

 

Returns

the newly created XfceRc object, or NULL on error.

[transfer full]

Since: 4.2


xfce_rc_close ()

void
xfce_rc_close (XfceRc *rc);

Destructs rc .

If rc was opened read-write and contains dirty (modified) entries, these will be flushed to permanent storage first.

Parameters

rc

an XfceRc object.

 

Since: 4.2


xfce_rc_flush ()

void
xfce_rc_flush (XfceRc *rc);

Flushes all changes that currently reside only in memory back to permanent storage. Dirty configuration entries are written in the most specific file available.

Parameters

rc

an XfceRc object.

 

Since: 4.2


xfce_rc_is_dirty ()

gboolean
xfce_rc_is_dirty (const XfceRc *rc);

Checks whether rc has any dirty (modified) entries.

Parameters

rc

an XfceRc object.

 

Returns

TRUE if rc has any dirty (modified) entries.

Since: 4.2


xfce_rc_is_readonly ()

gboolean
xfce_rc_is_readonly (const XfceRc *rc);

Returns the read-only status of rc .

Parameters

rc

an XfceRc object.

 

Returns

the read-only status.

Since: 4.2


xfce_rc_get_locale ()

const gchar *
xfce_rc_get_locale (const XfceRc *rc);

Returns current locale used by rc to lookup translated entries.

Parameters

rc

an XfceRc object.

 

Returns

a string representing the current locale.

Since: 4.2


xfce_rc_get_groups ()

gchar **
xfce_rc_get_groups (const XfceRc *rc);

Returns the names of all known groups in rc .

Since the default groups (the "NULL group") name is NULL, it will not be returned with this functions. But it does not matter at all, since the default group is known to always exist.

Parameters

rc

an XfceRc object.

 

Returns

a NULL-terminated string array will the names of all groups in rc . Should be freed using g_strfreev() when no longer needed.

[transfer full]

Since: 4.2


xfce_rc_get_entries ()

gchar **
xfce_rc_get_entries (const XfceRc *rc,
                     const gchar *group);

Returns the names of all entries in group if any.

NULL is a valid input value for group . xfce_rc_get_entries will then return all entries in the so called "NULL group". Though this "NULL group" should only be used for backward compatibility with old applications. You should not use it in newly written code.

Parameters

rc

an XfceRc object.

 

group

the name of the group to get entries from.

 

Returns

a NULL-terminated string array with all entries in group . Has to be freed using g_strfreev() if no longer needed. If the specified group does not exists, NULL is returned. If the group has no entries, an empty string array is returned.

[transfer full]

Since: 4.2


xfce_rc_delete_group ()

void
xfce_rc_delete_group (XfceRc *rc,
                      const gchar *group,
                      gboolean global);

If rc is a simple config object and group exists, it is deleted. All entries within group will be deleted. For simple config objects, global is ignored.

If rc is a complex config object and group exists, it will be deleted will all entries. If global is TRUE, the entry will be marked as deleted globally, therefore all calls to xfce_rc_read_entry and related functions will return the fallback values. If global is FALSE, the group will be deleted in the per-user config file, and further calls to xfce_rc_read_entry will most probably return the system-wide config entries.

Parameters

rc

an XfceRc object.

 

group

name of the group to delete.

 

global

whether to delete the group globally.

 

Since: 4.2


xfce_rc_get_group ()

const gchar *
xfce_rc_get_group (const XfceRc *rc);

Returns the name of the group in which we are searching for keys and from which we are retrieving entries. If the currently active group is the default group (the so called "NULL group"), NULL will be returned.

Parameters

rc

an XfceRc object.

 

Returns

the name of the current group.

Since: 4.2


xfce_rc_has_group ()

gboolean
xfce_rc_has_group (const XfceRc *rc,
                   const gchar *group);

Returns TRUE if the specified group is known about.

Parameters

rc

an XfceRc object.

 

group

the group to search for.

 

Returns

TRUE if the group exists.

Since: 4.2


xfce_rc_set_group ()

void
xfce_rc_set_group (XfceRc *rc,
                   const gchar *group);

Specifies the group in which keys will be read and written. Subsequent calls to xfce_rc_read_entry and xfce_rc_write_entry will be applied only in the active group.

If group references a group that does not exists, it will be created for you. But note, that empty groups will not be synced to permanent storage.

Parameters

rc

an XfceRc object.

 

group

the name of the new group or NULL to to switch back to the default group.

 

Since: 4.2


xfce_rc_delete_entry ()

void
xfce_rc_delete_entry (XfceRc *rc,
                      const gchar *key,
                      gboolean global);

Similar to xfce_rc_delete_group, but works on an entry in the current group.

Parameters

rc

an XfceRc object.

 

key

the key to delete.

 

global

whether to delete key globally.

 

Since: 4.2


xfce_rc_has_entry ()

gboolean
xfce_rc_has_entry (const XfceRc *rc,
                   const gchar *key);

Checks whether the key has an entry in the current group.

Parameters

rc

an XfceRc object.

 

key

the key to search for.

 

Returns

TRUE if the key is available, else FALSE.

Since: 4.2


xfce_rc_read_entry ()

const gchar *
xfce_rc_read_entry (const XfceRc *rc,
                    const gchar *key,
                    const gchar *fallback);

Reads the value of an entry specified by key in the current group.

Parameters

rc

an XfceRc object.

 

key

the key to search for.

 

fallback

a default value returned if the key was not found.

 

Returns

the value for this key , or fallback if key was not found.

Since: 4.2


xfce_rc_read_entry_untranslated ()

const gchar *
xfce_rc_read_entry_untranslated (const XfceRc *rc,
                                 const gchar *key,
                                 const gchar *fallback);

Reads the value of an entry specified by key in the current group. The untranslated entry is returned. You normally do not need this.

Parameters

rc

an XfceRc object.

 

key

the key to search for.

 

fallback

a default value returned if the key was not found.

 

Returns

the untranslated value for this key , or fallback if key was not found.

Since: 4.2


xfce_rc_read_bool_entry ()

gboolean
xfce_rc_read_bool_entry (const XfceRc *rc,
                         const gchar *key,
                         gboolean fallback);

Reads the value of an entry specified by key in the current group and interpret it as a boolean value. Currently "on", "true" and "yes" are accepted as true, everything else is false.

Parameters

rc

an XfceRc object.

 

key

the key to search for.

 

fallback

a default value returned if the key was not found.

 

Returns

the value for this key .

Since: 4.2


xfce_rc_read_int_entry ()

gint
xfce_rc_read_int_entry (const XfceRc *rc,
                        const gchar *key,
                        gint fallback);

Reads the value of an entry specified by key in the current group and interprets it as an integer value.

Parameters

rc

an XfceRc object.

 

key

the key to search for.

 

fallback

a default value returned if the key was not found.

 

Returns

the value for this key .

Since: 4.2


xfce_rc_read_list_entry ()

gchar **
xfce_rc_read_list_entry (const XfceRc *rc,
                         const gchar *key,
                         const gchar *delimiter);

Reads a list of strings in the entry specified by key in the current group. The returned list has to be freed using g_strfreev() when no longer needed.

Parameters

rc

an XfceRc object.

 

key

the key to search for.

 

delimiter

a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings. If NULL, "," is used.

 

Returns

the list or NULL if the entry does not exist.

[transfer full]

Since: 4.2


xfce_rc_rollback ()

void
xfce_rc_rollback (XfceRc *rc);

Mark rc as "clean", i.e. don't write dirty entries at destruction time. If you then call xfce_rc_write_entry again, the dirty flag is set again and dirty entries will be written at a subsequent xfce_rc_flush call.

Parameters

rc

an XfceRc object.

 

Since: 4.2


xfce_rc_write_entry ()

void
xfce_rc_write_entry (XfceRc *rc,
                     const gchar *key,
                     const gchar *value);

Writes a key /value pair. This has no effect if the resource config was opened readonly, else the value will be written to permanent storage on the next call to xfce_rc_flush or when rc is destroyed using xfce_rc_close.

If rc was opened using xfce_rc_config_open, the value will be written to the most specific config file.

Parameters

rc

an XfceRc object.

 

key

the key to write.

 

value

the value to write.

 

Since: 4.2


xfce_rc_write_bool_entry ()

void
xfce_rc_write_bool_entry (XfceRc *rc,
                          const gchar *key,
                          gboolean value);

Wrapper for xfce_rc_write_entry, that stores a boolean value .

Parameters

rc

an XfceRc object.

 

key

the key to write.

 

value

the value to write.

 

Since: 4.2


xfce_rc_write_int_entry ()

void
xfce_rc_write_int_entry (XfceRc *rc,
                         const gchar *key,
                         gint value);

Wrapper for xfce_rc_write_entry, that stores an integer value .

Parameters

rc

an XfceRc object.

 

key

the key to write.

 

value

the value to write.

 

Since: 4.2


xfce_rc_write_list_entry ()

void
xfce_rc_write_list_entry (XfceRc *rc,
                          const gchar *key,
                          gchar **value,
                          const gchar *separator);

Wrapper for xfce_rc_write_entry, that stores a string list value .

Parameters

rc

an XfceRc object.

 

key

the key to write.

 

value

a NULL terminated list of strings to store in the entry specified by key.

 

separator

the list separator. Defaults to "," if NULL.

 

Since: 4.2

Types and Values

XfceRc

typedef struct {
  void          (*close)        (XfceRc       *rc);
  void          (*flush)        (XfceRc       *rc);
  void          (*rollback)     (XfceRc       *rc);
  gboolean      (*is_dirty)     (const XfceRc *rc);
  gboolean      (*is_readonly)  (const XfceRc *rc);
  gchar       **(*get_groups)   (const XfceRc *rc);
  gchar       **(*get_entries)  (const XfceRc *rc,
                                 const gchar  *group);
  void          (*delete_group) (XfceRc       *rc,
                                 const gchar  *group, gboolean global);
  const gchar  *(*get_group)    (const XfceRc *rc);
  gboolean      (*has_group)    (const XfceRc *rc,
                                 const gchar  *group);
  void          (*set_group)    (XfceRc       *rc,
                                 const gchar  *group);
  void          (*delete_entry) (XfceRc       *rc,
                                 const gchar *key,
                                 gboolean     global);
  gboolean      (*has_entry)    (const XfceRc *rc,
                                 const gchar  *key);
  const gchar  *(*read_entry)   (const XfceRc *rc,
                                 const gchar  *key,
                                 gboolean      translated);
  /* write_entry == NULL means readonly */
  void          (*write_entry)  (XfceRc       *rc,
                                 const gchar  *key,
                                 const gchar  *value);

  gchar   *locale;
} XfceRc;