X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=mp4.h;h=c36a1f81db84bbe8c0f6a800f74a75f36cc2d93b;hp=7e9d24b81052878be666e5b7d096758f1407894e;hb=HEAD;hpb=bcb1b6fdd7a95348403f77d209c09e885654f672

diff --git a/mp4.h b/mp4.h
index 7e9d24b8..c36a1f81 100644
--- a/mp4.h
+++ b/mp4.h
@@ -1,44 +1,87 @@
+/** \file mp4.h Public API of the mp4 parser. */
+
+/**
+ * Callbacks provided by the user of the mp4 parsing API.
+ *
+ * A pointer to this structure is passed to the two public open functions. If
+ * the file is opened in read-only mode, the ->write() and ->truncate() methods
+ * won't be called and may thus be NULL. The ->read() and ->seek() methods
+ * must be supplied for either open type.
+ *
+ * All methods are supposed to work like their corresponding system calls.
+ * That is, they should return non-negative for success and -1 on failure. In
+ * the error case errno is expected to be set accordingly.
+ *
+ * \sa \ref mp4_open(), \ref mp4_open_meta().
+ */
 struct mp4_callback {
-    uint32_t (*read)(void *user_data, void *buffer, uint32_t length);
-    uint32_t (*write)(void *udata, void *buffer, uint32_t length);
-    uint32_t (*seek)(void *user_data, uint64_t position);
-    uint32_t (*truncate)(void *user_data);
-    void *user_data;
+	/** This pointer is propagated to each call of all methods. */
+	void *user_data;
+	/**
+	 * This should return the number of bytes read on success. Short reads
+	 * are OK: the function may return less than length.
+	 */
+	ssize_t (*read)(void *user_data, void *buffer, size_t length);
+	/**
+	 * This method is assumed to succeed. The implementation should simply
+	 * abort on errors. Note that offsets beyond EOF must not be regarded
+	 * as invalid arguments.
+	 */
+	off_t (*seek)(void *user_data, off_t offset, int whence);
+	/**
+	 * Like the write() system call, this should return the number of bytes
+	 * written. Short writes are OK: the function may return less than
+	 * count.
+	 */
+	ssize_t (*write)(void *user_data, void *buffer, size_t count);
+	/**
+	 * Unlike the truncate system call, this function does not receive an
+	 * offset. The method is expected to truncate the file to the offset
+	 * given by the current file position instead.
+	 */
+	int (*truncate)(void *user_data);
 };
 
+/** Specifies one metadata tag. Both fields are 0-terminated strings. */
 struct mp4_tag {
-    char *item;
-    char *value;
-    uint32_t len;
+	/** The item name: "artist", "title", "album", "comment", or "date". */
+	char *item;
+	/** An arbitrary string value. */
+	char *value;
 };
 
+/**
+ * An array of name/value pairs.
+ *
+ * This structure is initialized when the mp4 file is opened in either mode.
+ * If the file contains metadata items other than the standard five, those
+ * non-standard items are not included in the array. After a successful open, a
+ * pointer to the metadata structure can be obtained via \ref mp4_get_meta().
+ */
 struct mp4_metadata {
-    struct mp4_tag *tags;
-    uint32_t count;
+	/** It's OK to change this, for example by calling realloc(). */
+	struct mp4_tag *tags;
+	/** The number of entries of the array. */
+	unsigned count;
 };
 
-struct mp4; /* opaque */
+/**
+ * The mp4 file handle.
+ *
+ * A pointer to this opaque structure is returned by the two open functions.
+ * All other functions of the mp4 API receive a pointer of this type.
+ */
+struct mp4;
 
-void mp4_set_sample_position(struct mp4 *f, int32_t track, int32_t sample);
-int32_t mp4_total_tracks(const struct mp4 *f);
-bool mp4_is_audio_track(const struct mp4 *f, int32_t track);
-struct mp4 *mp4_open_read(const struct mp4_callback *cb);
+int mp4_set_sample_position(struct mp4 *f, uint32_t sample);
+int mp4_open(const struct mp4_callback *cb, struct mp4 **result);
 void mp4_close(struct mp4 *f);
-int32_t mp4_get_sample_size(const struct mp4 *f, int track, int sample);
-uint32_t mp4_get_sample_rate(const struct mp4 *f, int32_t track);
-uint32_t mp4_get_channel_count(const struct mp4 * f, int32_t track);
-int32_t mp4_num_samples(const struct mp4 *f, int track);
-uint64_t mp4_get_duration(const struct mp4 *f, int32_t track);
-struct mp4 *mp4_open_meta(const struct mp4_callback *cb);
-
-int mp4_meta_get_by_index(const struct mp4 *f, unsigned int index,
-                            char **item, char **value);
-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);
+int mp4_get_sample_size(const struct mp4 *f, uint32_t sample, uint32_t *result);
+uint16_t mp4_get_sample_rate(const struct mp4 *f);
+uint16_t mp4_get_channel_count(const struct mp4 *f);
+uint32_t mp4_num_samples(const struct mp4 *f);
+uint64_t mp4_get_duration(const struct mp4 *f);
+int mp4_open_meta(const struct mp4_callback *cb, struct mp4 **result);
+struct mp4_metadata *mp4_get_meta(struct mp4 *f);
+int mp4_update_meta(struct mp4 *f);
+__malloc char *mp4_get_tag_value(const struct mp4 *f, const char *item);