1/***************************************************************************
2 copyright : (C) 2006 by Lukáš Lalinský
3 email : lalinsky@gmail.com
4
5 copyright : (C) 2004 by Allan Sandfeld Jensen
6 email : kde@carewolf.org
7 (original MPC implementation)
8 ***************************************************************************/
9
10/***************************************************************************
11 * This library is free software; you can redistribute it and/or modify *
12 * it under the terms of the GNU Lesser General Public License version *
13 * 2.1 as published by the Free Software Foundation. *
14 * *
15 * This library is distributed in the hope that it will be useful, but *
16 * WITHOUT ANY WARRANTY; without even the implied warranty of *
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
18 * Lesser General Public License for more details. *
19 * *
20 * You should have received a copy of the GNU Lesser General Public *
21 * License along with this library; if not, write to the Free Software *
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
23 * 02110-1301 USA *
24 * *
25 * Alternatively, this file is available under the Mozilla Public *
26 * License Version 1.1. You may obtain a copy of the License at *
27 * http://www.mozilla.org/MPL/ *
28 ***************************************************************************/
29
30#ifndef TAGLIB_WVFILE_H
31#define TAGLIB_WVFILE_H
32
33#include "tfile.h"
34#include "taglib_export.h"
35#include "wavpackproperties.h"
36
37namespace TagLib {
38
39 class Tag;
40
41 namespace ID3v1 { class Tag; }
42 namespace APE { class Tag; }
43
44 //! An implementation of WavPack metadata
45
46 /*!
47 * This is implementation of WavPack metadata.
48 *
49 * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream
50 * properties from the file.
51 */
52
53 namespace WavPack {
54
55 //! An implementation of TagLib::File with WavPack specific methods
56
57 /*!
58 * This implements and provides an interface for WavPack files to the
59 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
60 * the abstract TagLib::File API as well as providing some additional
61 * information specific to WavPack files.
62 */
63
64 class TAGLIB_EXPORT File : public TagLib::File
65 {
66 public:
67 /*!
68 * This set of flags is used for various operations and is suitable for
69 * being OR-ed together.
70 */
71 enum TagTypes {
72 //! Empty set. Matches no tag types.
73 NoTags = 0x0000,
74 //! Matches ID3v1 tags.
75 ID3v1 = 0x0001,
76 //! Matches APE tags.
77 APE = 0x0002,
78 //! Matches all tag types.
79 AllTags = 0xffff
80 };
81
82 /*!
83 * Constructs a WavPack file from \a file. If \a readProperties is true the
84 * file's audio properties will also be read using \a propertiesStyle. If
85 * false, \a propertiesStyle is ignored
86 */
87 File(FileName file, bool readProperties = true,
88 Properties::ReadStyle propertiesStyle = Properties::Average);
89
90 /*!
91 * Constructs an WavPack file from \a file. If \a readProperties is true the
92 * file's audio properties will also be read using \a propertiesStyle. If
93 * false, \a propertiesStyle is ignored.
94 *
95 * \note TagLib will *not* take ownership of the stream, the caller is
96 * responsible for deleting it after the File object.
97 */
98 File(IOStream *stream, bool readProperties = true,
99 Properties::ReadStyle propertiesStyle = Properties::Average);
100
101 /*!
102 * Destroys this instance of the File.
103 */
104 virtual ~File();
105
106 /*!
107 * Returns the Tag for this file. This will be an APE tag, an ID3v1 tag
108 * or a combination of the two.
109 */
110 virtual TagLib::Tag *tag() const;
111
112 /*!
113 * Implements the unified property interface -- export function.
114 * If the file contains both an APE and an ID3v1 tag, only APE
115 * will be converted to the PropertyMap.
116 */
117 PropertyMap properties() const;
118
119 void removeUnsupportedProperties(const StringList &properties);
120
121 /*!
122 * Implements the unified property interface -- import function.
123 * Creates an APE tag if it does not exists and calls setProperties() on
124 * that. Any existing ID3v1 tag will be updated as well.
125 */
126 PropertyMap setProperties(const PropertyMap&);
127
128 /*!
129 * Returns the MPC::Properties for this file. If no audio properties
130 * were read then this will return a null pointer.
131 */
132 virtual Properties *audioProperties() const;
133
134 /*!
135 * Saves the file.
136 *
137 * This returns true if the save was successful.
138 */
139 virtual bool save();
140
141 /*!
142 * Returns a pointer to the ID3v1 tag of the file.
143 *
144 * If \a create is false (the default) this may return a null pointer
145 * if there is no valid ID3v1 tag. If \a create is true it will create
146 * an ID3v1 tag if one does not exist and returns a valid pointer.
147 *
148 * \note This may return a valid pointer regardless of whether or not the
149 * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file
150 * on disk actually has an ID3v1 tag.
151 *
152 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
153 * deleted by the user. It will be deleted when the file (object) is
154 * destroyed.
155 *
156 * \see hasID3v1Tag()
157 */
158 ID3v1::Tag *ID3v1Tag(bool create = false);
159
160 /*!
161 * Returns a pointer to the APE tag of the file.
162 *
163 * If \a create is false (the default) this may return a null pointer
164 * if there is no valid APE tag. If \a create is true it will create
165 * an APE tag if one does not exist and returns a valid pointer.
166 *
167 * \note This may return a valid pointer regardless of whether or not the
168 * file on disk has an APE tag. Use hasAPETag() to check if the file
169 * on disk actually has an APE tag.
170 *
171 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
172 * deleted by the user. It will be deleted when the file (object) is
173 * destroyed.
174 *
175 * \see hasAPETag()
176 */
177 APE::Tag *APETag(bool create = false);
178
179 /*!
180 * This will remove the tags that match the OR-ed together TagTypes from the
181 * file. By default it removes all tags.
182 *
183 * \note This will also invalidate pointers to the tags
184 * as their memory will be freed.
185 * \note In order to make the removal permanent save() still needs to be called
186 */
187 void strip(int tags = AllTags);
188
189 /*!
190 * Returns whether or not the file on disk actually has an ID3v1 tag.
191 *
192 * \see ID3v1Tag()
193 */
194 bool hasID3v1Tag() const;
195
196 /*!
197 * Returns whether or not the file on disk actually has an APE tag.
198 *
199 * \see APETag()
200 */
201 bool hasAPETag() const;
202
203 private:
204 File(const File &);
205 File &operator=(const File &);
206
207 void read(bool readProperties);
208
209 class FilePrivate;
210 FilePrivate *d;
211 };
212 }
213}
214
215#endif
216