mp4: Simplify and doxify meta tag accessors.

The integer return value is redundant, so get rid of the value
parameter and simplify meta_find_by_name() accordingly. Document that
tag values are allocated on the heap and should be freed by the caller.

diff --git a/aac_afh.c b/aac_afh.c
index fdb0339c7715bf9e319c03bdf6990ecac1814313..d6ff4e936443a228a82950f5211b7f0c984f8105 100644 (file)
--- a/aac_afh.c
+++ b/aac_afh.c
@@ -118,11 +118,11 @@ static int aac_afh_get_chunk(uint32_t chunk_num, void *afh_context,
 
 static void _aac_afh_get_taginfo(const struct mp4 *mp4, struct taginfo *tags)
 {
-       mp4_meta_get_artist(mp4, &tags->artist);
-       mp4_meta_get_title(mp4, &tags->title);
-       mp4_meta_get_date(mp4, &tags->year);
-       mp4_meta_get_album(mp4, &tags->album);
-       mp4_meta_get_comment(mp4, &tags->comment);
+       tags->artist = mp4_meta_get_artist(mp4);
+       tags->title = mp4_meta_get_title(mp4);
+       tags->year = mp4_meta_get_date(mp4);
+       tags->album = mp4_meta_get_album(mp4);
+       tags->comment = mp4_meta_get_comment(mp4);
 }
 
 /*

diff --git a/mp4.c b/mp4.c
index d8aea78379aeabc80987481229c2e537cef8a93f..f576529c0a954967e327834ae2b4e0bd204f24e2 100644 (file)
--- a/mp4.c
+++ b/mp4.c
@@ -1747,47 +1747,70 @@ int32_t mp4_meta_update(const struct mp4_callback *cb,
        return 1;
 }
 
-/* find a metadata item by name */
-/* returns 0 if item found, 1 if no such item */
-static int32_t meta_find_by_name(const struct mp4 *f, const char *item,
-               char **value)
+static char *meta_find_by_name(const struct mp4 *f, const char *item)
 {
        uint32_t i;
 
-       for (i = 0; i < f->tags.count; i++) {
-               if (!strcasecmp(f->tags.tags[i].item, item)) {
-                       *value = para_strdup(f->tags.tags[i].value);
-                       return 1;
-               }
-       }
-
-       *value = NULL;
-
-       /* not found */
-       return 0;
+       for (i = 0; i < f->tags.count; i++)
+               if (!strcasecmp(f->tags.tags[i].item, item))
+                       return para_strdup(f->tags.tags[i].value);
+       return NULL;
 }
 
-int32_t mp4_meta_get_artist(const struct mp4 *f, char **value)
+/**
+ * Return the value of the artist meta tag of an mp4 file.
+ *
+ * \param f Must not be NULL.
+ *
+ * \return If the file does not contain this metadata tag, the function returns
+ * NULL. Otherwise, a copy of the tag value is returned. The caller should free
+ * this memory when it is no longer needed.
+ */
+char *mp4_meta_get_artist(const struct mp4 *f)
 {
-       return meta_find_by_name(f, "artist", value);
+       return meta_find_by_name(f, "artist");
 }
 
-int32_t mp4_meta_get_title(const struct mp4 *f, char **value)
+/**
+ * Return the value of the title meta tag of an mp4 file.
+ *
+ * \param f See \ref mp4_meta_get_artist().
+ * \return See \ref mp4_meta_get_artist().
+ */
+char *mp4_meta_get_title(const struct mp4 *f)
 {
-       return meta_find_by_name(f, "title", value);
+       return meta_find_by_name(f, "title");
 }
 
-int32_t mp4_meta_get_date(const struct mp4 *f, char **value)
+/**
+ * Return the value of the date meta tag of an mp4 file.
+ *
+ * \param f See \ref mp4_meta_get_artist().
+ * \return See \ref mp4_meta_get_artist().
+ */
+char *mp4_meta_get_date(const struct mp4 *f)
 {
-       return meta_find_by_name(f, "date", value);
+       return meta_find_by_name(f, "date");
 }
 
-int32_t mp4_meta_get_album(const struct mp4 *f, char **value)
+/**
+ * Return the value of the album meta tag of an mp4 file.
+ *
+ * \param f See \ref mp4_meta_get_artist().
+ * \return See \ref mp4_meta_get_artist().
+ */
+char *mp4_meta_get_album(const struct mp4 *f)
 {
-       return meta_find_by_name(f, "album", value);
+       return meta_find_by_name(f, "album");
 }
 
-int32_t mp4_meta_get_comment(const struct mp4 *f, char **value)
+/**
+ * Return the value of the comment meta tag of an mp4 file.
+ *
+ * \param f See \ref mp4_meta_get_artist().
+ * \return See \ref mp4_meta_get_artist().
+ */
+char *mp4_meta_get_comment(const struct mp4 *f)
 {
-       return meta_find_by_name(f, "comment", value);
+       return meta_find_by_name(f, "comment");
 }

diff --git a/mp4.h b/mp4.h
index 7e9d24b81052878be666e5b7d096758f1407894e..82bd6788bd5635eb9323bdb99163510e2462ba79 100644 (file)
--- a/mp4.h
+++ b/mp4.h
@@ -37,8 +37,8 @@ int32_t mp4_meta_update(const struct mp4_callback *cb,
                const struct mp4_metadata *data);
 
 int mp4_meta_get_num_items(const struct mp4 *f);
-int mp4_meta_get_artist(const struct mp4 *f, char **value);
-int mp4_meta_get_title(const struct mp4 *f, char **value);
-int mp4_meta_get_date(const struct mp4 *f, char **value);
-int mp4_meta_get_album(const struct mp4 *f, char **value);
-int mp4_meta_get_comment(const struct mp4 *f, char **value);
+char *mp4_meta_get_artist(const struct mp4 *f);
+char *mp4_meta_get_title(const struct mp4 *f);
+char *mp4_meta_get_date(const struct mp4 *f);
+char *mp4_meta_get_album(const struct mp4 *f);
+char *mp4_meta_get_comment(const struct mp4 *f);