1 /***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
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. *
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. *
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
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 ***************************************************************************/
26 #ifndef TAGLIB_ID3V2TAG_H
27 #define TAGLIB_ID3V2TAG_H
30 #include "tbytevector.h"
34 #include "taglib_export.h"
36 #include "id3v2framefactory.h"
42 //! An ID3v2 implementation
45 * This is a relatively complete and flexible framework for working with ID3v2
57 typedef List<Frame *> FrameList;
58 typedef Map<ByteVector, FrameList> FrameListMap;
60 //! The main class in the ID3v2 implementation
63 * This is the main class in the ID3v2 implementation. It serves two
64 * functions. This first, as is obvious from the public API, is to provide a
65 * container for the other ID3v2 related classes. In addition, through the
66 * read() and parse() protected methods, it provides the most basic level of
67 * parsing. In these methods the ID3v2 tag is extracted from the file and
68 * split into data components.
70 * ID3v2 tags have several parts, TagLib attempts to provide an interface
71 * for them all. header(), footer() and extendedHeader() corespond to those
72 * data structures in the ID3v2 standard and the APIs for the classes that
73 * they return attempt to reflect this.
75 * Also ID3v2 tags are built up from a list of frames, which are in turn
76 * have a header and a list of fields. TagLib provides two ways of accessing
77 * the list of frames that are in a given ID3v2 tag. The first is simply
78 * via the frameList() method. This is just a list of pointers to the frames.
79 * The second is a map from the frame type -- i.e. "COMM" for comments -- and
80 * a list of frames of that type. (In some cases ID3v2 allows for multiple
81 * frames of the same type, hence this being a map to a list rather than just
82 * a map to an individual frame.)
84 * More information on the structure of frames can be found in the ID3v2::Frame
87 * read() and parse() pass binary data to the other ID3v2 class structures,
88 * they do not handle parsing of flags or fields, for instace. Those are
89 * handled by similar functions within those classes.
91 * \note All pointers to data structures within the tag will become invalid
92 * when the tag is destroyed.
94 * \warning Dealing with the nasty details of ID3v2 is not for the faint of
95 * heart and should not be done without much meditation on the spec. It's
96 * rather long, but if you're planning on messing with this class and others
97 * that deal with the details of ID3v2 (rather than the nice, safe, abstract
98 * TagLib::Tag and friends), it's worth your time to familiarize yourself
99 * with said spec (which is distrubuted with the TagLib sources). TagLib
100 * tries to do most of the work, but with a little luck, you can still
101 * convince it to generate invalid ID3v2 tags. The APIs for ID3v2 assume a
102 * working knowledge of ID3v2 structure. You're been warned.
105 class TAGLIB_EXPORT Tag : public TagLib::Tag
109 * Constructs an empty ID3v2 tag.
111 * \note You must create at least one frame for this tag to be valid.
116 * Constructs an ID3v2 tag read from \a file starting at \a tagOffset.
117 * \a factory specifies which FrameFactory will be used for the
118 * construction of new frames.
120 * \note You should be able to ignore the \a factory parameter in almost
121 * all situations. You would want to specify your own FrameFactory
122 * subclass in the case that you are extending TagLib to support additional
123 * frame types, which would be incorperated into your factory.
127 Tag(File *file, long tagOffset,
128 const FrameFactory *factory = FrameFactory::instance());
131 * Destroys this Tag instance.
135 // Reimplementations.
137 virtual String title() const;
138 virtual String artist() const;
139 virtual String album() const;
140 virtual String comment() const;
141 virtual String genre() const;
142 virtual uint year() const;
143 virtual uint track() const;
145 virtual void setTitle(const String &s);
146 virtual void setArtist(const String &s);
147 virtual void setAlbum(const String &s);
148 virtual void setComment(const String &s);
149 virtual void setGenre(const String &s);
150 virtual void setYear(uint i);
151 virtual void setTrack(uint i);
153 virtual bool isEmpty() const;
156 * Returns a pointer to the tag's header.
158 Header *header() const;
161 * Returns a pointer to the tag's extended header or null if there is no
164 ExtendedHeader *extendedHeader() const;
167 * Returns a pointer to the tag's footer or null if there is no footer.
169 * \deprecated I don't see any reason to keep this around since there's
170 * nothing useful to be retrieved from the footer, but well, again, I'm
171 * prone to change my mind, so this gets to stay around until near a
174 Footer *footer() const;
177 * Returns a reference to the frame list map. This is an FrameListMap of
178 * all of the frames in the tag.
180 * This is the most convenient structure for accessing the tag's frames.
181 * Many frame types allow multiple instances of the same frame type so this
182 * is a map of lists. In most cases however there will only be a single
183 * frame of a certain type.
185 * Let's say for instance that you wanted to access the frame for total
186 * beats per minute -- the TBPM frame.
189 * TagLib::MPEG::File f("foo.mp3");
191 * // Check to make sure that it has an ID3v2 tag
195 * // Get the list of frames for a specific frame type
197 * TagLib::ID3v2::FrameList l = f.ID3v2Tag()->frameListMap()["TBPM"];
200 * std::cout << l.front()->toString() << std::endl;
205 * \warning You should not modify this data structure directly, instead
206 * use addFrame() and removeFrame().
210 const FrameListMap &frameListMap() const;
213 * Returns a reference to the frame list. This is an FrameList of all of
214 * the frames in the tag in the order that they were parsed.
216 * This can be useful if for example you want iterate over the tag's frames
217 * in the order that they occur in the tag.
219 * \warning You should not modify this data structure directly, instead
220 * use addFrame() and removeFrame().
222 const FrameList &frameList() const;
225 * Returns the frame list for frames with the id \a frameID or an empty
226 * list if there are no frames of that type. This is just a convenience
227 * and is equivalent to:
230 * frameListMap()[frameID];
233 * \see frameListMap()
235 const FrameList &frameList(const ByteVector &frameID) const;
238 * Add a frame to the tag. At this point the tag takes ownership of
239 * the frame and will handle freeing its memory.
241 * \note Using this method will invalidate any pointers on the list
242 * returned by frameList()
244 void addFrame(Frame *frame);
247 * Remove a frame from the tag. If \a del is true the frame's memory
248 * will be freed; if it is false, it must be deleted by the user.
250 * \note Using this method will invalidate any pointers on the list
251 * returned by frameList()
253 void removeFrame(Frame *frame, bool del = true);
256 * Remove all frames of type \a id from the tag and free their memory.
258 * \note Using this method will invalidate any pointers on the list
259 * returned by frameList()
261 void removeFrames(const ByteVector &id);
264 * Render the tag back to binary data, suitable to be written to disk.
266 ByteVector render() const;
270 * Reads data from the file specified in the constructor. It does basic
271 * parsing of the data in the largest chunks. It partitions the tag into
272 * the Header, the body of the tag (which contains the ExtendedHeader and
273 * frames) and Footer.
278 * This is called by read to parse the body of the tag. It determines if an
279 * extended header exists and adds frames to the FrameListMap.
281 void parse(const ByteVector &data);
284 * Sets the value of the text frame with the Frame ID \a id to \a value.
285 * If the frame does not exist, it is created.
287 void setTextFrame(const ByteVector &id, const String &value);
291 Tag &operator=(const Tag &);