1/***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
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_VORBISCOMMENT_H
27#define TAGLIB_VORBISCOMMENT_H
28
29#include "tag.h"
30#include "tlist.h"
31#include "tmap.h"
32#include "tstring.h"
33#include "tstringlist.h"
34#include "tbytevector.h"
35#include "flacpicture.h"
36#include "taglib_export.h"
37
38namespace TagLib {
39
40 namespace Ogg {
41
42 /*!
43 * A mapping between a list of field names, or keys, and a list of values
44 * associated with that field.
45 *
46 * \see XiphComment::fieldListMap()
47 */
48 typedef Map<String, StringList> FieldListMap;
49
50 //! Ogg Vorbis comment implementation
51
52 /*!
53 * This class is an implementation of the Ogg Vorbis comment specification,
54 * to be found in section 5 of the Ogg Vorbis specification. Because this
55 * format is also used in other (currently unsupported) Xiph.org formats, it
56 * has been made part of a generic implementation rather than being limited
57 * to strictly Vorbis.
58 *
59 * Vorbis comments are a simple vector of keys and values, called fields.
60 * Multiple values for a given key are supported.
61 *
62 * \see fieldListMap()
63 */
64
65 class TAGLIB_EXPORT XiphComment : public TagLib::Tag
66 {
67 public:
68 /*!
69 * Constructs an empty Vorbis comment.
70 */
71 XiphComment();
72
73 /*!
74 * Constructs a Vorbis comment from \a data.
75 */
76 XiphComment(const ByteVector &data);
77
78 /*!
79 * Destroys this instance of the XiphComment.
80 */
81 virtual ~XiphComment();
82
83 virtual String title() const;
84 virtual String artist() const;
85 virtual String album() const;
86 virtual String comment() const;
87 virtual String genre() const;
88 virtual unsigned int year() const;
89 virtual unsigned int track() const;
90
91 virtual void setTitle(const String &s);
92 virtual void setArtist(const String &s);
93 virtual void setAlbum(const String &s);
94 virtual void setComment(const String &s);
95 virtual void setGenre(const String &s);
96 virtual void setYear(unsigned int i);
97 virtual void setTrack(unsigned int i);
98
99 virtual bool isEmpty() const;
100
101 /*!
102 * Returns the number of fields present in the comment.
103 */
104 unsigned int fieldCount() const;
105
106 /*!
107 * Returns a reference to the map of field lists. Because Xiph comments
108 * support multiple fields with the same key, a pure Map would not work.
109 * As such this is a Map of string lists, keyed on the comment field name.
110 *
111 * The standard set of Xiph/Vorbis fields (which may or may not be
112 * contained in any specific comment) is:
113 *
114 * <ul>
115 * <li>TITLE</li>
116 * <li>VERSION</li>
117 * <li>ALBUM</li>
118 * <li>ARTIST</li>
119 * <li>PERFORMER</li>
120 * <li>COPYRIGHT</li>
121 * <li>ORGANIZATION</li>
122 * <li>DESCRIPTION</li>
123 * <li>GENRE</li>
124 * <li>DATE</li>
125 * <li>LOCATION</li>
126 * <li>CONTACT</li>
127 * <li>ISRC</li>
128 * </ul>
129 *
130 * For a more detailed description of these fields, please see the Ogg
131 * Vorbis specification, section 5.2.2.1.
132 *
133 * \note The Ogg Vorbis comment specification does allow these key values
134 * to be either upper or lower case. However, it is conventional for them
135 * to be upper case. As such, TagLib, when parsing a Xiph/Vorbis comment,
136 * converts all fields to uppercase. When you are using this data
137 * structure, you will need to specify the field name in upper case.
138 *
139 * \warning You should not modify this data structure directly, instead
140 * use addField() and removeField().
141 */
142 const FieldListMap &fieldListMap() const;
143
144 /*!
145 * Implements the unified property interface -- export function.
146 * The result is a one-to-one match of the Xiph comment, since it is
147 * completely compatible with the property interface (in fact, a Xiph
148 * comment is nothing more than a map from tag names to list of values,
149 * as is the dict interface).
150 */
151 PropertyMap properties() const;
152
153 /*!
154 * Implements the unified property interface -- import function.
155 * The tags from the given map will be stored one-to-one in the file,
156 * except for invalid keys (less than one character, non-ASCII, or
157 * containing '=' or '~') in which case the according values will
158 * be contained in the returned PropertyMap.
159 */
160 PropertyMap setProperties(const PropertyMap&);
161
162 /*!
163 * Check if the given String is a valid Xiph comment key.
164 */
165 static bool checkKey(const String&);
166
167 /*!
168 * Returns the vendor ID of the Ogg Vorbis encoder. libvorbis 1.0 as the
169 * most common case always returns "Xiph.Org libVorbis I 20020717".
170 */
171 String vendorID() const;
172
173 /*!
174 * Add the field specified by \a key with the data \a value. If \a replace
175 * is true, then all of the other fields with the same key will be removed
176 * first.
177 *
178 * If the field value is empty, the field will be removed.
179 */
180 void addField(const String &key, const String &value, bool replace = true);
181
182 /*!
183 * Remove the field specified by \a key with the data \a value. If
184 * \a value is null, all of the fields with the given key will be removed.
185 *
186 * \deprecated Using this method may lead to a linkage error.
187 */
188 // BIC: remove and merge with below
189 void removeField(const String &key, const String &value = String::null);
190
191 /*!
192 * Remove all the fields specified by \a key.
193 *
194 * \see removeAllFields()
195 */
196 void removeFields(const String &key);
197
198 /*!
199 * Remove all the fields specified by \a key with the data \a value.
200 *
201 * \see removeAllFields()
202 */
203 void removeFields(const String &key, const String &value);
204
205 /*!
206 * Remove all the fields in the comment.
207 *
208 * \see removeFields()
209 */
210 void removeAllFields();
211
212 /*!
213 * Returns true if the field is contained within the comment.
214 *
215 * \note This is safer than checking for membership in the FieldListMap.
216 */
217 bool contains(const String &key) const;
218
219 /*!
220 * Renders the comment to a ByteVector suitable for inserting into a file.
221 */
222 ByteVector render() const; // BIC: remove and merge with below
223
224 /*!
225 * Renders the comment to a ByteVector suitable for inserting into a file.
226 *
227 * If \a addFramingBit is true the standard Vorbis comment framing bit will
228 * be appended. However some formats (notably FLAC) do not work with this
229 * in place.
230 */
231 ByteVector render(bool addFramingBit) const;
232
233
234 /*!
235 * Returns a list of pictures attached to the xiph comment.
236 */
237 List<FLAC::Picture *> pictureList();
238
239 /*!
240 * Removes an picture. If \a del is true the picture's memory
241 * will be freed; if it is false, it must be deleted by the user.
242 */
243 void removePicture(FLAC::Picture *picture, bool del = true);
244
245 /*!
246 * Remove all pictures.
247 */
248 void removeAllPictures();
249
250 /*!
251 * Add a new picture to the comment block. The comment block takes ownership of the
252 * picture and will handle freeing its memory.
253 *
254 * \note The file will be saved only after calling save().
255 */
256 void addPicture(FLAC::Picture *picture);
257
258 protected:
259 /*!
260 * Reads the tag from the file specified in the constructor and fills the
261 * FieldListMap.
262 */
263 void parse(const ByteVector &data);
264
265 private:
266 XiphComment(const XiphComment &);
267 XiphComment &operator=(const XiphComment &);
268
269 class XiphCommentPrivate;
270 XiphCommentPrivate *d;
271 };
272 }
273}
274
275#endif
276