[libmediaart] Documentation fixes
- From: Sam Thursfield <sthursfield src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libmediaart] Documentation fixes
- Date: Thu, 17 Oct 2013 09:22:35 +0000 (UTC)
commit c1a11f0d4c24a5e6a86e706109654c420d76af9d
Author: Sam Thursfield <sam thursfield codethink co uk>
Date: Wed Oct 16 20:22:51 2013 +0100
Documentation fixes
.../reference/libmediaart/libmediaart-sections.txt | 6 +-
libmediaart/cache.c | 18 +++++-
libmediaart/extract.c | 69 ++++++++++++++++++--
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);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]