## Resource lookup functions

Resource lookup functions —

## Functions

gboolean | (*XfceMatchFunc) ()
gchar ** | xfce_resource_dirs ()
gchar * | xfce_resource_lookup ()
gchar ** | xfce_resource_lookup_all ()
gchar ** | xfce_resource_match ()
gchar ** | xfce_resource_match_custom ()
void | xfce_resource_push_path ()
void | xfce_resource_pop_path ()
gchar * | xfce_resource_save_location ()

## Types and Values

enum | XfceResourceType

## Includes

    #include <libxfce4util/libxfce4util.h>

## Description

## Functions

### XfceMatchFunc ()

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

Return value :

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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", ...).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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!

#### Parameters

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.

#### Parameters

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

## Types and Values

### enum XfceResourceType

#### Members

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