1/***************************************************************************
2 copyright : (C) 2003 by Allan Sandfeld Jensen
3 email : kde@carewolf.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_FLACFILE_H
27#define TAGLIB_FLACFILE_H
28
29#include "taglib_export.h"
30#include "tfile.h"
31#include "tlist.h"
32#include "tag.h"
33
34#include "flacpicture.h"
35#include "flacproperties.h"
36
37namespace TagLib {
38
39 class Tag;
40 namespace ID3v2 { class FrameFactory; class Tag; }
41 namespace ID3v1 { class Tag; }
42 namespace Ogg { class XiphComment; }
43
44 //! An implementation of FLAC metadata
45
46 /*!
47 * This is implementation of FLAC metadata for non-Ogg FLAC files. At some
48 * point when Ogg / FLAC is more common there will be a similar implementation
49 * under the Ogg hierarchy.
50 *
51 * This supports ID3v1, ID3v2 and Xiph style comments as well as reading stream
52 * properties from the file.
53 */
54
55 namespace FLAC {
56
57 //! An implementation of TagLib::File with FLAC specific methods
58
59 /*!
60 * This implements and provides an interface for FLAC files to the
61 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
62 * the abstract TagLib::File API as well as providing some additional
63 * information specific to FLAC files.
64 */
65
66 class TAGLIB_EXPORT File : public TagLib::File
67 {
68 public:
69 /*!
70 * This set of flags is used for various operations and is suitable for
71 * being OR-ed together.
72 */
73 enum TagTypes {
74 //! Empty set. Matches no tag types.
75 NoTags = 0x0000,
76 //! Matches Vorbis comments.
77 XiphComment = 0x0001,
78 //! Matches ID3v1 tags.
79 ID3v1 = 0x0002,
80 //! Matches ID3v2 tags.
81 ID3v2 = 0x0004,
82 //! Matches all tag types.
83 AllTags = 0xffff
84 };
85
86 /*!
87 * Constructs a FLAC file from \a file. If \a readProperties is true the
88 * file's audio properties will also be read.
89 *
90 * \note In the current implementation, \a propertiesStyle is ignored.
91 *
92 * \deprecated This constructor will be dropped in favor of the one below
93 * in a future version.
94 */
95 File(FileName file, bool readProperties = true,
96 Properties::ReadStyle propertiesStyle = Properties::Average);
97
98 /*!
99 * Constructs an FLAC file from \a file. If \a readProperties is true the
100 * file's audio properties will also be read.
101 *
102 * If this file contains and ID3v2 tag the frames will be created using
103 * \a frameFactory.
104 *
105 * \note In the current implementation, \a propertiesStyle is ignored.
106 */
107 // BIC: merge with the above constructor
108 File(FileName file, ID3v2::FrameFactory *frameFactory,
109 bool readProperties = true,
110 Properties::ReadStyle propertiesStyle = Properties::Average);
111
112 /*!
113 * Constructs a FLAC file from \a stream. If \a readProperties is true the
114 * file's audio properties will also be read.
115 *
116 * \note TagLib will *not* take ownership of the stream, the caller is
117 * responsible for deleting it after the File object.
118 *
119 * If this file contains and ID3v2 tag the frames will be created using
120 * \a frameFactory.
121 *
122 * \note In the current implementation, \a propertiesStyle is ignored.
123 */
124 // BIC: merge with the above constructor
125 File(IOStream *stream, ID3v2::FrameFactory *frameFactory,
126 bool readProperties = true,
127 Properties::ReadStyle propertiesStyle = Properties::Average);
128
129 /*!
130 * Destroys this instance of the File.
131 */
132 virtual ~File();
133
134 /*!
135 * Returns the Tag for this file. This will be a union of XiphComment,
136 * ID3v1 and ID3v2 tags.
137 *
138 * \see ID3v2Tag()
139 * \see ID3v1Tag()
140 * \see XiphComment()
141 */
142 virtual TagLib::Tag *tag() const;
143
144 /*!
145 * Implements the unified property interface -- export function.
146 * If the file contains more than one tag (e.g. XiphComment and ID3v1),
147 * only the first one (in the order XiphComment, ID3v2, ID3v1) will be
148 * converted to the PropertyMap.
149 */
150 PropertyMap properties() const;
151
152 void removeUnsupportedProperties(const StringList &);
153
154 /*!
155 * Implements the unified property interface -- import function.
156 * This always creates a Xiph comment, if none exists. The return value
157 * relates to the Xiph comment only.
158 * Ignores any changes to ID3v1 or ID3v2 comments since they are not allowed
159 * in the FLAC specification.
160 */
161 PropertyMap setProperties(const PropertyMap &);
162
163 /*!
164 * Returns the FLAC::Properties for this file. If no audio properties
165 * were read then this will return a null pointer.
166 */
167 virtual Properties *audioProperties() const;
168
169 /*!
170 * Save the file. This will primarily save the XiphComment, but
171 * will also keep any old ID3-tags up to date. If the file
172 * has no XiphComment, one will be constructed from the ID3-tags.
173 *
174 * This returns true if the save was successful.
175 */
176 virtual bool save();
177
178 /*!
179 * Returns a pointer to the ID3v2 tag of the file.
180 *
181 * If \a create is false (the default) this returns a null pointer
182 * if there is no valid ID3v2 tag. If \a create is true it will create
183 * an ID3v2 tag if one does not exist and returns a valid pointer.
184 *
185 * \note This may return a valid pointer regardless of whether or not the
186 * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file
187 * on disk actually has an ID3v2 tag.
188 *
189 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
190 * deleted by the user. It will be deleted when the file (object) is
191 * destroyed.
192 *
193 * \see hasID3v2Tag()
194 */
195 ID3v2::Tag *ID3v2Tag(bool create = false);
196
197 /*!
198 * Returns a pointer to the ID3v1 tag of the file.
199 *
200 * If \a create is false (the default) this returns a null pointer
201 * if there is no valid APE tag. If \a create is true it will create
202 * an APE tag if one does not exist and returns a valid pointer.
203 *
204 * \note This may return a valid pointer regardless of whether or not the
205 * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file
206 * on disk actually has an ID3v1 tag.
207 *
208 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
209 * deleted by the user. It will be deleted when the file (object) is
210 * destroyed.
211 *
212 * \see hasID3v1Tag()
213 */
214 ID3v1::Tag *ID3v1Tag(bool create = false);
215
216 /*!
217 * Returns a pointer to the XiphComment for the file.
218 *
219 * If \a create is false (the default) this returns a null pointer
220 * if there is no valid XiphComment. If \a create is true it will create
221 * a XiphComment if one does not exist and returns a valid pointer.
222 *
223 * \note This may return a valid pointer regardless of whether or not the
224 * file on disk has a XiphComment. Use hasXiphComment() to check if the
225 * file on disk actually has a XiphComment.
226 *
227 * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
228 * deleted by the user. It will be deleted when the file (object) is
229 * destroyed.
230 *
231 * \see hasXiphComment()
232 */
233 Ogg::XiphComment *xiphComment(bool create = false);
234
235 /*!
236 * Set the ID3v2::FrameFactory to something other than the default. This
237 * can be used to specify the way that ID3v2 frames will be interpreted
238 * when
239 *
240 * \see ID3v2FrameFactory
241 * \deprecated This value should be passed in via the constructor
242 */
243 void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
244
245 /*!
246 * Returns the block of data used by FLAC::Properties for parsing the
247 * stream properties.
248 *
249 * \deprecated Always returns an empty vector.
250 */
251 ByteVector streamInfoData(); // BIC: remove
252
253 /*!
254 * Returns the length of the audio-stream, used by FLAC::Properties for
255 * calculating the bitrate.
256 *
257 * \deprecated Always returns zero.
258 */
259 long streamLength(); // BIC: remove
260
261 /*!
262 * Returns a list of pictures attached to the FLAC file.
263 */
264 List<Picture *> pictureList();
265
266 /*!
267 * Removes an attached picture. If \a del is true the picture's memory
268 * will be freed; if it is false, it must be deleted by the user.
269 */
270 void removePicture(Picture *picture, bool del = true);
271
272 /*!
273 * Remove all attached images.
274 */
275 void removePictures();
276
277 /*!
278 * Add a new picture to the file. The file takes ownership of the
279 * picture and will handle freeing its memory.
280 *
281 * \note The file will be saved only after calling save().
282 */
283 void addPicture(Picture *picture);
284
285 /*!
286 * This will remove the tags that match the OR-ed together TagTypes from
287 * the file. By default it removes all tags.
288 *
289 * \warning This will also invalidate pointers to the tags as their memory
290 * will be freed.
291 *
292 * \note In order to make the removal permanent save() still needs to be
293 * called.
294 *
295 * \note This won't remove the Vorbis comment block completely. The
296 * vendor ID will be preserved.
297 */
298 void strip(int tags = AllTags);
299
300 /*!
301 * Returns whether or not the file on disk actually has a XiphComment.
302 *
303 * \see xiphComment()
304 */
305 bool hasXiphComment() const;
306
307 /*!
308 * Returns whether or not the file on disk actually has an ID3v1 tag.
309 *
310 * \see ID3v1Tag()
311 */
312 bool hasID3v1Tag() const;
313
314 /*!
315 * Returns whether or not the file on disk actually has an ID3v2 tag.
316 *
317 * \see ID3v2Tag()
318 */
319 bool hasID3v2Tag() const;
320
321 private:
322 File(const File &);
323 File &operator=(const File &);
324
325 void read(bool readProperties);
326 void scan();
327
328 class FilePrivate;
329 FilePrivate *d;
330 };
331 }
332}
333
334#endif
335