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_TRUEAUDIOFILE_H |
31 | #define TAGLIB_TRUEAUDIOFILE_H |
32 | |
33 | #include "tfile.h" |
34 | #include "trueaudioproperties.h" |
35 | |
36 | namespace TagLib { |
37 | |
38 | class Tag; |
39 | |
40 | namespace ID3v2 { class Tag; class FrameFactory; } |
41 | namespace ID3v1 { class Tag; } |
42 | |
43 | //! An implementation of TrueAudio metadata |
44 | |
45 | /*! |
46 | * This is implementation of TrueAudio metadata. |
47 | * |
48 | * This supports ID3v1 and ID3v2 tags as well as reading stream |
49 | * properties from the file. |
50 | */ |
51 | |
52 | namespace TrueAudio { |
53 | |
54 | //! An implementation of TagLib::File with TrueAudio specific methods |
55 | |
56 | /*! |
57 | * This implements and provides an interface for TrueAudio files to the |
58 | * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing |
59 | * the abstract TagLib::File API as well as providing some additional |
60 | * information specific to TrueAudio files. |
61 | */ |
62 | |
63 | class TAGLIB_EXPORT File : public TagLib::File |
64 | { |
65 | public: |
66 | /*! |
67 | * This set of flags is used for various operations and is suitable for |
68 | * being OR-ed together. |
69 | */ |
70 | enum TagTypes { |
71 | //! Empty set. Matches no tag types. |
72 | NoTags = 0x0000, |
73 | //! Matches ID3v1 tags. |
74 | ID3v1 = 0x0001, |
75 | //! Matches ID3v2 tags. |
76 | ID3v2 = 0x0002, |
77 | //! Matches all tag types. |
78 | AllTags = 0xffff |
79 | }; |
80 | |
81 | /*! |
82 | * Constructs a TrueAudio file from \a file. If \a readProperties is true |
83 | * the file's audio properties will also be read. |
84 | * |
85 | * \note In the current implementation, \a propertiesStyle is ignored. |
86 | */ |
87 | File(FileName file, bool readProperties = true, |
88 | Properties::ReadStyle propertiesStyle = Properties::Average); |
89 | |
90 | /*! |
91 | * Constructs a TrueAudio file from \a file. If \a readProperties is true |
92 | * the file's audio properties will also be read. |
93 | * |
94 | * If this file contains and ID3v2 tag the frames will be created using |
95 | * \a frameFactory. |
96 | * |
97 | * \note In the current implementation, \a propertiesStyle is ignored. |
98 | */ |
99 | File(FileName file, ID3v2::FrameFactory *frameFactory, |
100 | bool readProperties = true, |
101 | Properties::ReadStyle propertiesStyle = Properties::Average); |
102 | |
103 | /*! |
104 | * Constructs a TrueAudio file from \a stream. If \a readProperties is true |
105 | * the file's audio properties will also be read. |
106 | * |
107 | * \note TagLib will *not* take ownership of the stream, the caller is |
108 | * responsible for deleting it after the File object. |
109 | * |
110 | * \note In the current implementation, \a propertiesStyle is ignored. |
111 | */ |
112 | File(IOStream *stream, bool readProperties = true, |
113 | Properties::ReadStyle propertiesStyle = Properties::Average); |
114 | |
115 | /*! |
116 | * Constructs a TrueAudio file from \a stream. If \a readProperties is true |
117 | * the file's audio properties will also be read. |
118 | * |
119 | * \note TagLib will *not* take ownership of the stream, the caller is |
120 | * responsible for deleting it after the File object. |
121 | * |
122 | * If this file contains and ID3v2 tag the frames will be created using |
123 | * \a frameFactory. |
124 | * |
125 | * \note In the current implementation, \a propertiesStyle is ignored. |
126 | */ |
127 | File(IOStream *stream, ID3v2::FrameFactory *frameFactory, |
128 | bool readProperties = true, |
129 | Properties::ReadStyle propertiesStyle = Properties::Average); |
130 | |
131 | /*! |
132 | * Destroys this instance of the File. |
133 | */ |
134 | virtual ~File(); |
135 | |
136 | /*! |
137 | * Returns the Tag for this file. |
138 | */ |
139 | virtual TagLib::Tag *tag() const; |
140 | |
141 | /*! |
142 | * Implements the unified property interface -- export function. |
143 | * If the file contains both ID3v1 and v2 tags, only ID3v2 will be |
144 | * converted to the PropertyMap. |
145 | */ |
146 | PropertyMap properties() const; |
147 | |
148 | /*! |
149 | * Implements the unified property interface -- import function. |
150 | * Creates in ID3v2 tag if necessary. If an ID3v1 tag exists, it will |
151 | * be updated as well, within the limitations of ID3v1. |
152 | */ |
153 | PropertyMap setProperties(const PropertyMap &); |
154 | |
155 | void removeUnsupportedProperties(const StringList &properties); |
156 | |
157 | /*! |
158 | * Returns the TrueAudio::Properties for this file. If no audio properties |
159 | * were read then this will return a null pointer. |
160 | */ |
161 | virtual Properties *audioProperties() const; |
162 | |
163 | /*! |
164 | * Set the ID3v2::FrameFactory to something other than the default. |
165 | * |
166 | * \see ID3v2FrameFactory |
167 | */ |
168 | void setID3v2FrameFactory(const ID3v2::FrameFactory *factory); |
169 | |
170 | /*! |
171 | * Saves the file. |
172 | */ |
173 | virtual bool save(); |
174 | |
175 | /*! |
176 | * Returns a pointer to the ID3v1 tag of the file. |
177 | * |
178 | * If \a create is false (the default) this may return a null pointer |
179 | * if there is no valid ID3v1 tag. If \a create is true it will create |
180 | * an ID3v1 tag if one does not exist and returns a valid pointer. |
181 | * |
182 | * \note This may return a valid pointer regardless of whether or not the |
183 | * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file |
184 | * on disk actually has an ID3v1 tag. |
185 | * |
186 | * \note The Tag <b>is still</b> owned by the MPEG::File and should not be |
187 | * deleted by the user. It will be deleted when the file (object) is |
188 | * destroyed. |
189 | * |
190 | * \see hasID3v1Tag() |
191 | */ |
192 | ID3v1::Tag *ID3v1Tag(bool create = false); |
193 | |
194 | /*! |
195 | * Returns a pointer to the ID3v2 tag of the file. |
196 | * |
197 | * If \a create is false (the default) this may return a null pointer |
198 | * if there is no valid ID3v2 tag. If \a create is true it will create |
199 | * an ID3v2 tag if one does not exist and returns a valid pointer. |
200 | * |
201 | * \note This may return a valid pointer regardless of whether or not the |
202 | * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file |
203 | * on disk actually has an ID3v2 tag. |
204 | * |
205 | * \note The Tag <b>is still</b> owned by the MPEG::File and should not be |
206 | * deleted by the user. It will be deleted when the file (object) is |
207 | * destroyed. |
208 | * |
209 | * \see hasID3v2Tag() |
210 | */ |
211 | ID3v2::Tag *ID3v2Tag(bool create = false); |
212 | |
213 | /*! |
214 | * This will remove the tags that match the OR-ed together TagTypes from the |
215 | * file. By default it removes all tags. |
216 | * |
217 | * \note This will also invalidate pointers to the tags |
218 | * as their memory will be freed. |
219 | * \note In order to make the removal permanent save() still needs to be called |
220 | */ |
221 | void strip(int tags = AllTags); |
222 | |
223 | /*! |
224 | * Returns whether or not the file on disk actually has an ID3v1 tag. |
225 | * |
226 | * \see ID3v1Tag() |
227 | */ |
228 | bool hasID3v1Tag() const; |
229 | |
230 | /*! |
231 | * Returns whether or not the file on disk actually has an ID3v2 tag. |
232 | * |
233 | * \see ID3v2Tag() |
234 | */ |
235 | bool hasID3v2Tag() const; |
236 | |
237 | private: |
238 | File(const File &); |
239 | File &operator=(const File &); |
240 | |
241 | void read(bool readProperties, Properties::ReadStyle propertiesStyle); |
242 | void scan(); |
243 | long findID3v1(); |
244 | long findID3v2(); |
245 | |
246 | class FilePrivate; |
247 | FilePrivate *d; |
248 | }; |
249 | } |
250 | } |
251 | |
252 | #endif |
253 | |