## Caching and Management

Caching and Management — Caching and management of stored media art.

## Functions

void | media_art_get_file ()
void | media_art_get_path ()
gboolean | media_art_remove ()
gchar * | media_art_strip_invalid_entities ()

## Object Hierarchy

## Includes

    #include <libmediaart/mediaart.h>

## Description

These functions give you access to the media art that has been extracted and saved in the user's XDG_CACHE_HOME directory.

To find the media art for a given media file, use the function `media_art_get_file()` (you can also use `media_art_get_path()`, which does the same thing but for path strings instead of GFile objects).

If media art for the file is not found in the cache, these functions will return `NULL`. You may find some embedded media art upon loading the file, and you can use `media_art_process()` to convert it to the correct format and save it in the cache for next time. The `media_art_process()` function also supports searching for external media art images using a basic heuristic.

## Functions

### media_art_get_file ()

    void
    media_art_get_file (const gchar *artist,
                        const gchar *title,
                        const gchar *prefix,
                        GFile *file,
                        GFile **cache_file,
                        GFile **local_file);

Gets the files pointing to cache files suitable for storing the media art provided by the `artist` , `title` and `file` arguments. `cache_file` will point to a location in the XDG user cache directory, meanwhile `local_file` will point to a cache file that resides in the same filesystem than `file` .

When done, both GFiles must be freed with `g_object_unref()` if non-`NULL`.

#### Parameters

artist | the artist |
title | the title |
prefix | the prefix for cache files, for example "album" |
file | the file or `NULL`. | [allow-none]
cache_file | the location to store a GFile pointing to the user cache path, or `NULL`. | [out][transfer full][allow-none]
local_file | the location to store a GFile pointing to a cache file in the same filesystem than `file` , or `NULL`. | [out][transfer full][allow-none]

Since 0.2.0

### media_art_get_path ()

    void
    media_art_get_path (const gchar *artist,
                        const gchar *title,
                        const gchar *prefix,
                        const gchar *uri,
                        gchar **path,
                        gchar **local_uri);

Get the path to media art for a given resource. Newly allocated data in `path` and `local_uri` must be freed with `g_free()`.

#### Parameters

artist | the artist |
title | the title |
prefix | the prefix, for example "album" |
uri | the uri of the file or `NULL`. | [allow-none]
path | the location to store the local path or `NULL`. | [out][transfer full][allow-none]
local_uri | the location to store the local uri or `NULL`. | [out][transfer full][allow-none]

Since 0.2.0

### media_art_remove ()

    gboolean
    media_art_remove (const gchar *artist,
                      const gchar *album);

Removes media art for given album/artist/etc provided.

#### Parameters

artist | artist the media art belongs to |
album | album the media art belongs or `NULL`. | [allow-none]

#### Returns

TRUE on success, otherwise FALSE.

Since 0.2.0

### media_art_strip_invalid_entities ()

    gchar *
    media_art_strip_invalid_entities (const gchar *original);

Strip a albumname or artistname string to prepare it for calculating the media art path with it. Certain characters and charactersets will be stripped and a newly allocated string returned which you must free with `g_free()`.

This functions is used internally by `media_art_get_file()` and `media_art_get_path()`. You will not normally need to call it yourself.

This function provides the following features:

1. Invalid characters include: ()[]<>{}_!@#$^&*+=|\/"'?~;

2. Text inside brackets `of()`, {}, [] and <> pairs are removed.

3. Multiples of space characters are removed.

#### Parameters

original | original string |

#### Returns

`original` stripped of invalid characters which must be freed. On error or if `original` is empty, `NULL` is returned.

Since 0.2.0

## Types and Values