diff options
author | Sam Thursfield <sam.thursfield@codethink.co.uk> | 2013-10-16 20:22:51 +0100 |
---|---|---|
committer | Sam Thursfield <sam.thursfield@codethink.co.uk> | 2013-10-17 10:21:49 +0100 |
commit | c1a11f0d4c24a5e6a86e706109654c420d76af9d (patch) | |
tree | 30334b1881b794af82ffe8d1e1d05e1c66e22b4f | |
parent | 0cba167b96624364afe31a80868f366c291d494b (diff) | |
download | libmediaart-c1a11f0d4c24a5e6a86e706109654c420d76af9d.tar.gz |
Documentation fixes
-rw-r--r-- | docs/reference/libmediaart/libmediaart-sections.txt | 6 | ||||
-rw-r--r-- | libmediaart/cache.c | 18 | ||||
-rw-r--r-- | libmediaart/extract.c | 69 | ||||
-rw-r--r-- | libmediaart/extract.h | 2 |
4 files changed, 86 insertions, 9 deletions
diff --git a/docs/reference/libmediaart/libmediaart-sections.txt b/docs/reference/libmediaart/libmediaart-sections.txt index e92a3cd..cca4ecf 100644 --- a/docs/reference/libmediaart/libmediaart-sections.txt +++ b/docs/reference/libmediaart/libmediaart-sections.txt @@ -1,16 +1,18 @@ <SECTION> <FILE>cache</FILE> +media_art_get_file media_art_get_path -media_art_strip_invalid_entities media_art_remove +media_art_strip_invalid_entities </SECTION> <SECTION> <FILE>extract</FILE> MediaArtType media_art_init -media_art_process media_art_shutdown +media_art_process_file +media_art_process </SECTION> <SECTION> diff --git a/libmediaart/cache.c b/libmediaart/cache.c index e2592b6..acf187a 100644 --- a/libmediaart/cache.c +++ b/libmediaart/cache.c @@ -32,6 +32,19 @@ * @title: Caching and Management * @short_description: Caching and management of stored media art. * @include: libmediaart/mediaart.h + * + * 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. **/ static gboolean @@ -78,6 +91,9 @@ media_art_strip_find_next_block (const gchar *original, * 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. + * * Returns: copy of original but then stripped * * Since: 0.2.0 @@ -214,7 +230,7 @@ media_art_checksum_for_data (GChecksumType checksum_type, * @local_file will point to a cache file that resides in the same * filesystem than @file. * - * When done, both #GFile<!-- -->s must be freed with g_object_unref if + * When done, both #GFile<!-- -->s must be freed with g_object_unref() if * non-%NULL. * * Since: 0.2.0 diff --git a/libmediaart/extract.c b/libmediaart/extract.c index bc157a8..baed4eb 100644 --- a/libmediaart/extract.c +++ b/libmediaart/extract.c @@ -41,6 +41,31 @@ * @title: Extraction * @short_description: Extraction of music and movie art. * @include: libmediaart/mediaart.h + * + * The libmediaart library supports taking image data that you have extracted + * from a media file and saving it into the media art cache, so that in future + * applications can display the media art without having to extract the image + * again. This is done using the media_art_process_file() function. + * + * Extracting the media art from the file needs to be done by your application. + * Usually, when an application loads a media file any embedded images will be + * made available as a side effect. For example, if you are using GStreamer any + * images will be returned through the #GstTagList interface as %GST_TAG_IMAGE + * tags. + * + * The media art cache requires that all images are saved as 'application/jpeg' + * files. Embedded images can be in several formats, and + * media_art_process_file() will convert the supplied image data into the + * correct format if necessary. There are multiple backends that can be used + * for this, and you can choose which is used at build time using the library's + * 'configure' script. + * + * If there is no embedded media art in a file, media_art_process_file() will + * look in the directory that contains the media file for likely media art + * using a simple heuristic. + * + * You must call media_art_init() before using the functions in libmediaart, + * and call media_art_shutdown() to free the resources it uses. **/ static const gchar *media_art_type_name[MEDIA_ART_TYPE_COUNT] = { @@ -934,6 +959,13 @@ media_art_queue_cb (GObject *source_object, file_info_free (fi); } +/** + * media_art_init: + * + * Initialise libmediaart. + * + * Returns: %TRUE if initialisation was successful, %FALSE otherwise. + */ gboolean media_art_init (void) { @@ -966,6 +998,11 @@ media_art_init (void) return TRUE; } +/** + * media_art_shutdown: + * + * Free the image processing backend and other resources used by libmediaart. + */ void media_art_shutdown (void) { @@ -1071,17 +1108,24 @@ get_mtime_by_uri (const gchar *uri) * @buffer: (allow-none): a buffer containing @file data, or %NULL * @len: length of @buffer, or 0 * @type: The type of media - * @mime: MIME type of @file, or %NULL + * @mime: MIME type of @buffer, or %NULL * @artist: The media file artist name, or %NULL * @title: The media file title, or %NULL * @file: File to be processed * - * Processes a media file, extracting any found media art. If @file - * is on a removable filesystem, the saved cache file will be local - * to it. + * Processes a media file. If you have extracted any embedded media art and + * passed this in as @buffer, the image data will be converted to the correct + * format and saved in the media art cache. + * + * If @buffer is %NULL, libmediaart will search the parent directory of @file + * for image files that are likely to be media art for @file, and if one is + * found it will be saved in the media art cache. + * + * If @file is on a removable filesystem, the media art file will be saved in a + * cache on the removable file system rather than on the host machine. * * Returns: #TRUE if the file could be processed. - **/ + */ gboolean media_art_process_file (const guchar *buffer, gsize len, @@ -1235,6 +1279,21 @@ media_art_process_file (const guchar *buffer, } +/** + * media_art_process: + * @buffer: A buffer of binary image data + * @len: The length of @buffer, in bytes + * @mime: The MIME type of the data stored in @buffer + * @type: The type of media that contained the image data + * @artist: (allow-none): Artist name of the media + * @title: (allow-none): Title of the media + * @uri: URI of the media file that contained the image data + * + * This function is the same as media_art_process_file(), but takes the URI as + * a string rather than a #GFile object. + * + * Returns: %TRUE in case of success, %FALSE otherwise. + */ gboolean media_art_process (const unsigned char *buffer, size_t len, diff --git a/libmediaart/extract.h b/libmediaart/extract.h index ff6c3ac..8b521cf 100644 --- a/libmediaart/extract.h +++ b/libmediaart/extract.h @@ -60,7 +60,7 @@ gboolean media_art_process (const unsigned char *buffer, gboolean media_art_process_file (const guchar *buffer, gsize len, MediaArtType type, - const gchar *mimetype, + const gchar *mime, const gchar *artist, const gchar *title, GFile *file); |