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