From: Andre Noll <maan@tuebingen.mpg.de>
Date: Fri, 13 Aug 2021 18:51:38 +0000 (+0200)
Subject: mp4: Simplify and doxify meta tag accessors.
X-Git-Tag: v0.7.1~7^2~86
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=3fecc9a4654398b856f5722af298aa61f9407d9f;p=paraslash.git

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 fdb0339c..d6ff4e93 100644
--- 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 d8aea783..f576529c 100644
--- 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 7e9d24b8..82bd6788 100644
--- 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);