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