1/***************************************************************************
2 copyright : (C) 2004 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_MPCFILE_H
27#define TAGLIB_MPCFILE_H
28
29#include "taglib_export.h"
30#include "tfile.h"
31#include "tag.h"
32
33#include "mpcproperties.h"
34
35#include "tlist.h"
36
37namespace TagLib {
38
39 class Tag;
40
41 namespace ID3v1 { class Tag; }
42 namespace APE { class Tag; }
43
44 //! An implementation of MPC metadata
45
46 /*!
47 * This is implementation of MPC metadata.
48 *
49 * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream
50 * properties from the file. ID3v2 tags are invalid in MPC-files, but will be skipped
51 * and ignored.
52 */
53
54 namespace MPC {
55
56 //! An implementation of TagLib::File with MPC specific methods
57
58 /*!
59 * This implements and provides an interface for MPC files to the
60 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
61 * the abstract TagLib::File API as well as providing some additional
62 * information specific to MPC files.
63 * The only invalid tag combination supported is an ID3v1 tag after an APE tag.
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 ID3v1 tags.
77 ID3v1 = 0x0001,
78 //! Matches ID3v2 tags.
79 ID3v2 = 0x0002,
80 //! Matches APE tags.
81 APE = 0x0004,
82 //! Matches all tag types.
83 AllTags = 0xffff
84 };
85
86 /*!
87 * Constructs an MPC 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 MPC 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 the APE
121 * tag will be converted to the PropertyMap.
122 */
123 PropertyMap properties() const;
124
125 void removeUnsupportedProperties(const StringList &properties);
126
127 /*!
128 * Implements the unified property interface -- import function.
129 * Affects only the APEv2 tag which will be created if necessary.
130 * If an ID3v1 tag exists, it will be updated as well.
131 */
132 PropertyMap setProperties(const PropertyMap &);
133
134 /*!
135 * Returns the MPC::Properties for this file. If no audio properties
136 * were read then this will return a null pointer.
137 */
138 virtual Properties *audioProperties() const;
139
140 /*!
141 * Saves the file.
142 *
143 * This returns true if the save was successful.
144 */
145 virtual bool save();
146
147 /*!
148 * Returns a pointer to the ID3v1 tag of the file.
149 *
150 * If \a create is false (the default) this returns a null pointer
151 * if there is no valid APE tag. If \a create is true it will create
152 * an APE tag if one does not exist and returns a valid pointer.
153 *
154 * \note This may return a valid pointer regardless of whether or not the
155 * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file
156 * on disk actually has an ID3v1 tag.
157 *
158 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
159 * deleted by the user. It will be deleted when the file (object) is
160 * destroyed.
161 *
162 * \see hasID3v1Tag()
163 */
164 ID3v1::Tag *ID3v1Tag(bool create = false);
165
166 /*!
167 * Returns a pointer to the APE tag of the file.
168 *
169 * If \a create is false (the default) this may return a null pointer
170 * if there is no valid APE tag. If \a create is true it will create
171 * an APE tag if one does not exist and returns a valid pointer. If
172 * there already be an ID3v1 tag, the new APE tag will be placed before it.
173 *
174 * \note This may return a valid pointer regardless of whether or not the
175 * file on disk has an APE tag. Use hasAPETag() to check if the file
176 * on disk actually has an APE tag.
177 *
178 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
179 * deleted by the user. It will be deleted when the file (object) is
180 * destroyed.
181 *
182 * \see hasAPETag()
183 */
184 APE::Tag *APETag(bool create = false);
185
186 /*!
187 * This will remove the tags that match the OR-ed together TagTypes from the
188 * file. By default it removes all tags.
189 *
190 * \warning This will also invalidate pointers to the tags
191 * as their memory will be freed.
192 *
193 * \note In order to make the removal permanent save() still needs to be called.
194 */
195 void strip(int tags = AllTags);
196
197 /*!
198 * \deprecated
199 * \see strip
200 */
201 void remove(int tags = AllTags);
202
203 /*!
204 * Returns whether or not the file on disk actually has an ID3v1 tag.
205 *
206 * \see ID3v1Tag()
207 */
208 bool hasID3v1Tag() const;
209
210 /*!
211 * Returns whether or not the file on disk actually has an APE tag.
212 *
213 * \see APETag()
214 */
215 bool hasAPETag() const;
216
217 private:
218 File(const File &);
219 File &operator=(const File &);
220
221 void read(bool readProperties);
222
223 class FilePrivate;
224 FilePrivate *d;
225 };
226 }
227}
228
229#endif
230