Resource lookup functions

## Resource lookup functions Resource lookup functions |

## Synopsis

    #include <libxfce4util/libxfce4util.h>

    enum                XfceResourceType;
    gboolean            (*XfceMatchFunc)                    (const gchar *basedir,
                                                             const gchar *relpath,
                                                             gpointer user_data);
    gchar**             xfce_resource_dirs                  (XfceResourceType type);
    gchar*              xfce_resource_lookup                (XfceResourceType type,
                                                             const gchar *filename);
    gchar**             xfce_resource_lookup_all            (XfceResourceType type,
                                                             const gchar *filename);
    gchar**             xfce_resource_match                 (XfceResourceType type,
                                                             const gchar *pattern,
                                                             gboolean unique);
    gchar**             xfce_resource_match_custom          (XfceResourceType type,
                                                             gboolean unique,
                                                             XfceMatchFunc func,
                                                             gpointer user_data);
    void                xfce_resource_push_path             (XfceResourceType type,
                                                             const gchar *path);
    void                xfce_resource_pop_path              (XfceResourceType type);
    gchar*              xfce_resource_save_location         (XfceResourceType type,
                                                             const gchar *relpath,
                                                             gboolean create);

## Description

## Details

### enum XfceResourceType

    typedef enum /*< prefix=XFCE_RESOURCE_ >*/
    {
      XFCE_RESOURCE_DATA   = 0,
      XFCE_RESOURCE_CONFIG = 1,
      XFCE_RESOURCE_CACHE  = 2,
      XFCE_RESOURCE_ICONS  = 3,
      XFCE_RESOURCE_THEMES = 4,
    } XfceResourceType;

`XFCE_RESOURCE_DATA` | where applications store data.
`XFCE_RESOURCE_CONFIG` | configuration files.
`XFCE_RESOURCE_CACHE` | cached information.
`XFCE_RESOURCE_ICONS` | icon search path.
`XFCE_RESOURCE_THEMES` | themes search path.

### XfceMatchFunc ()

    gboolean            (*XfceMatchFunc)                    (const gchar *basedir,
                                                             const gchar *relpath,
                                                             gpointer user_data);

Return value :

`user_data` : | additional user data passed to `xfce_resource_match_custom()`.
Returns : |

### xfce_resource_dirs ()

    gchar**             xfce_resource_dirs                  (XfceResourceType type);

Queries the list of possible directories for the specified `type`. The first element of the list is always the save location for `type`. None of the directories returned in the list are garantied to exist.

This function should be rarely used. You should consider using `xfce_resource_lookup()`, `xfce_resource_lookup_dirs()` or `xfce_resource_match()` instead.

The returned list must be freed using `g_strfreev()`.

`type` : | type of the resource.
Returns : | list of possible directories for `type`.

Since 4.2

### xfce_resource_lookup ()

    gchar*              xfce_resource_lookup                (XfceResourceType type,
                                                             const gchar *filename);

Looks for a resource of the specified `type` whose relative path matches `filename`. `filename` can either reference a regular file, in which case it must not end with a slash character ('/'), or a directory, when `filename` contains a trailing slash character ('/').

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`type` : | type of resource to lookup.
`filename` : | relative filename of the resource, e.g. "xfwm4/xfwmrc".
Returns : | the absolute path to the first file or directory in the search path, that matches `filename` or `NULL` if no such file or directory could be found.

Since 4.2

### xfce_resource_lookup_all ()

    gchar**             xfce_resource_lookup_all            (XfceResourceType type,
                                                             const gchar *filename);

Similar to `xfce_resource_lookup()`, but returns all resource of the specified `type`, that whose name is `filename`.

The caller is responsible to free the returned string array using `g_strfreev()` when no longer needed.

`type` : | type of the resource to lookup.
`filename` : | relative file path. If `filename` contains a trailing slash character it is taken to reference a directory, else it is taken to reference a file.
Returns : |

Since 4.2

### xfce_resource_match ()

    gchar**             xfce_resource_match                 (XfceResourceType type,
                                                             const gchar *pattern,
                                                             gboolean unique);

Tries to find all resources with the specified `type`. The function will look into all specified directories and return all filenames in these directories. The returned filenames are given relative the base directories specified by `type`.

If `pattern` contains a trailing slash, xfce_resource_match looks only for directories that match `pattern`, else it'll only look for regular files. In case you are looking for directories, the returned entries will contain a trailing slash as well, so you can easily use them with other resource functions like xfce_resource_lookup or xfce_resource_save_location.

Example: xfce_resource_match (XFCE_RESOURCE_CONFIG, "foo/bar*") will probably return ("foo/bar", "foo/barbaz", ...).

`type` : | type of the resource to locate directories for.
`pattern` : | only accept filenames that fit to the pattern. The pattern needs to be a valid GPattern.
`unique` : | if `TRUE`, only return items which have unique suffixes.
Returns : | string array of all the relative paths whose names matches the given `pattern`. The return value has to be freed using `g_strfreev()` when no longer needed.

Since 4.2

### xfce_resource_match_custom ()

    gchar**             xfce_resource_match_custom          (XfceResourceType type,
                                                             gboolean unique,
                                                             XfceMatchFunc func,
                                                             gpointer user_data);

Yet to be implemented!

The caller is responsible to free the returned string array using `g_strfreev()` when no longer needed.

`type` : | type of the resource to locate directories for.
`unique` : | if `TRUE`, only return items which have unique suffixes.
Returns : |

Since 4.2

### xfce_resource_push_path ()

    void                xfce_resource_push_path             (XfceResourceType type,
                                                             const gchar *path);

Appends `path` to the search path list for `type`. This function was written primary for use within modules in larger applications, for example MCS plugins.

For example, if you need to add a specific path to the search path list in your MCS, you should call `xfce_resource_push_path()` prior to calling one of the resource search functions and call `xfce_resource_pop_path()` right afterwards.

`type` : | type of the resource which search list should be expanded.
`path` : | search path to add.

Since 4.2

### xfce_resource_pop_path ()

    void                xfce_resource_pop_path              (XfceResourceType type);

Undoes the effect of the latest call to `xfce_resource_push_path()`. You should take special care to call `xfce_resource_pop_path()` exactly same times as `xfce_resource_push_path()`, everything else might result in unwanted and maybe even undefined behaviour. You have been warned!

`type` : | type of the resource which search list should be shrinked.

Since 4.2

### xfce_resource_save_location ()

    gchar*              xfce_resource_save_location         (XfceResourceType type,
                                                             const gchar *relpath,
                                                             gboolean create);

If `relpath` contains a trailing slash ('/') character, `xfce_resource_save_location()` finds the directory to save files into for the given type in the user's home directory. All directories needed (including those given by `relpath`) will be created on demand if `create` if `TRUE`.

If `relpath` does not end with a slash ('/') character, it is taken to be the name of a file to return the save location for. All the directories needed will be created on demand if `create` is `TRUE`.

Specifying `NULL` or the empty string for `relpath` allows you to discover the base path for saving files of the specified `type`, though normally you should not need this.

`type` : | type of location to return.
`relpath` : | relative path of the resource.
`create` : | whether to create missing directory.
Returns : | the path where resources of the specified `type` should be saved or `NULL` on error. The returned string should be freed when no longer needed.

Since 4.2