## Cache

Cache — Caching and lookup of stored media art.

## Functions

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

## Includes

    #include <libmediaart/mediaart.h>

## Description

These functions give you access to the media art that has been extracted and saved. There are normally two places the media art will be located in. These locations store symlinks not real copies of the content:

- The user's XDG_CACHE_HOME directory (usually `~/.cache/media-art/`)

- The local file system's top level `.mediaartlocal` directory (for example `/media/martyn/pendrive/.mediaartlocal/`)

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_buffer()` to convert it to the correct format and save it in the cache for next time. The `media_art_process_file()` function also supports searching for external media art images using a basic heuristic.

## Functions

### media_art_get_path ()

    gboolean
    media_art_get_path (const gchar *artist,
                        const gchar *title,
                        const gchar *prefix,
                        gchar **cache_path);

This function calls `media_art_get_file()` by creating a GFile for `uri` and passing the same arguments to `media_art_get_file()`. For more details about what this function does, see `media_art_get_file()`.

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

All string inputs must be valid UTF8. Use `g_utf8_validate()` if the input has not already been validated.

#### Parameters

artist | the artist. | [allow-none]
title | the title. | [allow-none]
prefix | the prefix, for example "album". | [allow-none]
cache_path | a string representing the path to the cache for this media art path or `NULL`. | [out][transfer full][allow-none]

#### Returns

`TRUE` if `cache_path` was returned, otherwise `FALSE`.

Since: 0.2.0

### media_art_get_file ()

    gboolean
    media_art_get_file (const gchar *artist,
                        const gchar *title,
                        const gchar *prefix,
                        GFile **cache_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..

The `cache_file` relates to a symlink stored in XDG cache directories for the user. A `cache_file` would be expected to look like `file:///home/martyn/.cache/media-art/...`. This is normally the location that is most useful (assuming the cache has been extracted in the first place).

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

This operation should not use i/o, but it depends on the backend GFile implementation.

All string inputs must be valid UTF8. Use `g_utf8_validate()` if the input has not already been validated.

#### Parameters

artist | the artist. | [allow-none]
title | the title. | [allow-none]
prefix | the prefix for cache files, for example "album". | [allow-none]
cache_file | a pointer to a GFile which represents the cached file for media art, or `NULL` a GFile representing the user's cache path, or `NULL` GFile representing the location of the local media art. | [out][transfer full][allow-none]

#### Returns

`TRUE` if `cache_file` was returned, otherwise `FALSE`.

Since: 0.2.0

### media_art_remove ()

    gboolean
    media_art_remove (const gchar *artist,
                      const gchar *album,
                      GCancellable *cancellable,
                      GError **error);

Removes media art for given album/artist provided.

If `artist` and `album` are `NULL`, ALL media art cache is removed.

All string inputs must be valid UTF8. Use `g_utf8_validate()` if the input has not already been validated.

#### Parameters

artist | artist the media art belongs to |
album | album the media art belongs or `NULL`. | [allow-none]
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

TRUE on success, otherwise FALSE where `error` will be set.

Since: 0.2.0

### media_art_remove_async ()

    void
    media_art_remove_async (const gchar *artist,
                            const gchar *album,
                            gint io_priority,
                            GObject *source_object,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Removes media art for given album/artist provided. Precisely the same operation as `media_art_remove()` is performing, but asynchronously.

When all i/o for the operation is finished the `callback` will be called.

In case of a partial error the callback will be called with any succeeding items and no error, and on the next request the error will be reported. If a request is cancelled the callback will be called with `G_IO_ERROR_CANCELLED`.

During an async request no other sync and async calls are allowed, and will result in `G_IO_ERROR_PENDING` errors.

Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`.

All string inputs must be valid UTF8. Use `g_utf8_validate()` if the input has not already been validated.

#### Parameters

artist | artist the media art belongs to |
album | album the media art belongs or `NULL`. | [allow-none]
source_object | the GObject this task belongs to, can be `NULL`. | [allow-none]
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 0.7.0

### media_art_remove_finish ()

    gboolean
    media_art_remove_finish (GObject *source_object,
                             GAsyncResult *result,
                             GError **error);

Finishes the asynchronous operation started with `media_art_remove_async()`.

#### Parameters

source_object | the GObject this task belongs to, can be `NULL`. | [allow-none]
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` on success, otherwise `FALSE` when `error` will be set.

Since: 0.7.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.

This function expects that the input is valid UTF-8. Use `g_utf8_validate()` if the input has not already been validated.

#### Parameters

original | original string. | [nullable]

#### Returns

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

Since: 0.2.0