## 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
    {
      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);

`basedir` : |
`relpath` : |
`user_data` : |
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 ('/').

`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`.

`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!

`type` : | type of the resource to locate directories for.
`unique` : | if `TRUE`, only return items which have unique suffixes.
`func` : |
`user_data` : |
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