1/***************************************************************************
2 copyright : (C) 2012 by Tsuda Kageyu
3 email : tsuda.kageyu@gmail.com
4 ***************************************************************************/
5
6/***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
10 * *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
19 * 02110-1301 USA *
20 * *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
25
26#ifndef TAGLIB_INFOTAG_H
27#define TAGLIB_INFOTAG_H
28
29#include "tag.h"
30#include "tmap.h"
31#include "tstring.h"
32#include "tstringlist.h"
33#include "tbytevector.h"
34#include "taglib_export.h"
35
36namespace TagLib {
37
38 class File;
39
40 //! A RIFF INFO tag implementation.
41 namespace RIFF {
42 namespace Info {
43
44 typedef Map<ByteVector, String> FieldListMap;
45
46 //! A abstraction for the string to data encoding in Info tags.
47
48 /*!
49 * RIFF INFO tag has no clear definitions about character encodings.
50 * In practice, local encoding of each system is largely used and UTF-8 is
51 * popular too.
52 *
53 * Here is an option to read and write tags in your preferred encoding
54 * by subclassing this class, reimplementing parse() and render() and setting
55 * your reimplementation as the default with Info::Tag::setStringHandler().
56 *
57 * \see ID3v1::Tag::setStringHandler()
58 */
59
60 class TAGLIB_EXPORT StringHandler
61 {
62 public:
63 StringHandler();
64 ~StringHandler();
65
66 /*!
67 * Decode a string from \a data. The default implementation assumes that
68 * \a data is an UTF-8 character array.
69 */
70 virtual String parse(const ByteVector &data) const;
71
72 /*!
73 * Encode a ByteVector with the data from \a s. The default implementation
74 * assumes that \a s is an UTF-8 string.
75 */
76 virtual ByteVector render(const String &s) const;
77 };
78
79 //! The main class in the ID3v2 implementation
80
81 /*!
82 * This is the main class in the INFO tag implementation. RIFF INFO tag is a
83 * metadata format found in WAV audio and AVI video files. Though it is a part
84 * of Microsoft/IBM's RIFF specification, the author could not find the official
85 * documents about it. So, this implementation is referring to unofficial documents
86 * online and some applications' behaviors especially Windows Explorer.
87 */
88 class TAGLIB_EXPORT Tag : public TagLib::Tag
89 {
90 public:
91 /*!
92 * Constructs an empty INFO tag.
93 */
94 Tag();
95
96 /*!
97 * Constructs an INFO tag read from \a data which is contents of "LIST" chunk.
98 */
99 Tag(const ByteVector &data);
100
101 virtual ~Tag();
102
103 // Reimplementations
104
105 virtual String title() const;
106 virtual String artist() const;
107 virtual String album() const;
108 virtual String comment() const;
109 virtual String genre() const;
110 virtual unsigned int year() const;
111 virtual unsigned int track() const;
112
113 virtual void setTitle(const String &s);
114 virtual void setArtist(const String &s);
115 virtual void setAlbum(const String &s);
116 virtual void setComment(const String &s);
117 virtual void setGenre(const String &s);
118 virtual void setYear(unsigned int i);
119 virtual void setTrack(unsigned int i);
120
121 virtual bool isEmpty() const;
122
123 /*!
124 * Returns a copy of the internal fields of the tag. The returned map directly
125 * reflects the contents of the "INFO" chunk.
126 *
127 * \note Modifying this map does not affect the tag's internal data.
128 * Use setFieldText() and removeField() instead.
129 *
130 * \see setFieldText()
131 * \see removeField()
132 */
133 FieldListMap fieldListMap() const;
134
135 /*
136 * Gets the value of the field with the ID \a id.
137 */
138 String fieldText(const ByteVector &id) const;
139
140 /*
141 * Sets the value of the field with the ID \a id to \a s.
142 * If the field does not exist, it is created.
143 * If \s is empty, the field is removed.
144 *
145 * \note fieldId must be four-byte long pure ASCII string. This function
146 * performs nothing if fieldId is invalid.
147 */
148 void setFieldText(const ByteVector &id, const String &s);
149
150 /*
151 * Removes the field with the ID \a id.
152 */
153 void removeField(const ByteVector &id);
154
155 /*!
156 * Render the tag back to binary data, suitable to be written to disk.
157 *
158 * \note Returns empty ByteVector is the tag contains no fields.
159 */
160 ByteVector render() const;
161
162 /*!
163 * Sets the string handler that decides how the text data will be
164 * converted to and from binary data.
165 * If the parameter \a handler is null, the previous handler is
166 * released and default UTF-8 handler is restored.
167 *
168 * \note The caller is responsible for deleting the previous handler
169 * as needed after it is released.
170 *
171 * \see StringHandler
172 */
173 static void setStringHandler(const StringHandler *handler);
174
175 protected:
176 /*!
177 * Pareses the body of the tag in \a data.
178 */
179 void parse(const ByteVector &data);
180
181
182 private:
183 Tag(const Tag &);
184 Tag &operator=(const Tag &);
185
186 class TagPrivate;
187 TagPrivate *d;
188 };
189 }}
190}
191
192#endif
193