Caching and Management

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

## Synopsis

    #include <libmediaart/mediaart.h>

    void                media_art_get_file                  (const gchar *artist,
                                                             const gchar *title,
                                                             const gchar *prefix,
                                                             GFile *file,
                                                             GFile **cache_file,
                                                             GFile **local_file);
    void                media_art_get_path                  (const gchar *artist,
                                                             const gchar *title,
                                                             const gchar *prefix,
                                                             const gchar *uri,
                                                             gchar **path,
                                                             gchar **local_uri);
    gboolean            media_art_remove                    (const gchar *artist,
                                                             const gchar *album);
    gchar *             media_art_strip_invalid_entities    (const gchar *original);

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

## Details

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

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

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

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

`original` : | original string
Returns : | copy of original but then stripped

Since 0.2.0