]> git.tuebingen.mpg.de Git - paraslash.git/blob - mp4.h
Compile with -Wsuggest-attribute=malloc.
[paraslash.git] / mp4.h
1 /** \file mp4.h Public API of the mp4 parser. */
2
3 /**
4  * Callbacks provided by the user of the mp4 parsing API.
5  *
6  * A pointer to this structure is passed to the two public open functions. If
7  * the file is opened in read-only mode, the ->write() and ->truncate() methods
8  * won't be called and may thus be NULL. The ->read() and ->seek() methods
9  * must be supplied for either open type.
10  *
11  * All methods are supposed to work like their corresponding system calls.
12  * That is, they should return non-negative for success and -1 on failure. In
13  * the error case errno is expected to be set accordingly.
14  *
15  * \sa \ref mp4_open(), \ref mp4_open_meta().
16  */
17 struct mp4_callback {
18         /** This pointer is propagated to each call of all methods. */
19         void *user_data;
20         /**
21          * This should return the number of bytes read on success. Short reads
22          * are OK: the function may return less than length.
23          */
24         ssize_t (*read)(void *user_data, void *buffer, size_t length);
25         /**
26          * This method is assumed to succeed. The implementation should simply
27          * abort on errors. Note that offsets beyond EOF must not be regarded
28          * as invalid arguments.
29          */
30         off_t (*seek)(void *user_data, off_t offset, int whence);
31         /**
32          * Like the write() system call, this should return the number of bytes
33          * written. Short writes are OK: the function may return less than
34          * count.
35          */
36         ssize_t (*write)(void *user_data, void *buffer, size_t count);
37         /**
38          * Unlike the truncate system call, this function does not receive an
39          * offset. The method is expected to truncate the file to the offset
40          * given by the current file position instead.
41          */
42         int (*truncate)(void *user_data);
43 };
44
45 /** Specifies one metadata tag. Both fields are 0-terminated strings. */
46 struct mp4_tag {
47         /** The item name: "artist", "title", "album", "comment", or "date". */
48         char *item;
49         /** An arbitrary string value. */
50         char *value;
51 };
52
53 /**
54  * An array of name/value pairs.
55  *
56  * This structure is initialized when the mp4 file is opened in either mode.
57  * If the file contains metadata items other than the standard five, those
58  * non-standard items are not included in the array. After a successful open, a
59  * pointer to the metadata structure can be obtained via \ref mp4_get_meta().
60  */
61 struct mp4_metadata {
62         /** It's OK to change this, for example by calling realloc(). */
63         struct mp4_tag *tags;
64         /** The number of entries of the array. */
65         unsigned count;
66 };
67
68 /**
69  * The mp4 file handle.
70  *
71  * A pointer to this opaque structure is returned by the two open functions.
72  * All other functions of the mp4 API receive a pointer of this type.
73  */
74 struct mp4;
75
76 int mp4_set_sample_position(struct mp4 *f, uint32_t sample);
77 int mp4_open(const struct mp4_callback *cb, struct mp4 **result);
78 void mp4_close(struct mp4 *f);
79 int mp4_get_sample_size(const struct mp4 *f, uint32_t sample, uint32_t *result);
80 uint16_t mp4_get_sample_rate(const struct mp4 *f);
81 uint16_t mp4_get_channel_count(const struct mp4 *f);
82 uint32_t mp4_num_samples(const struct mp4 *f);
83 uint64_t mp4_get_duration(const struct mp4 *f);
84 int mp4_open_meta(const struct mp4_callback *cb, struct mp4 **result);
85 struct mp4_metadata *mp4_get_meta(struct mp4 *f);
86 int mp4_update_meta(struct mp4 *f);
87 __malloc char *mp4_get_tag_value(const struct mp4 *f, const char *item);