← Back to branch summary

~ubuntu-branches/ubuntu/utopic/ardour3/utopic

« back to all changes in this revision

Viewing changes to libs/taglib/taglib/mpeg/id3v2/id3v2tag.h

  • Committer: Package Import Robot
  • Author(s): Felipe Sateler
  • Date: 2013-09-21 19:05:02 UTC
  • Revision ID: package-import@ubuntu.com-20130921190502-8gsftrku6jnzhd7v
Tags: upstream-3.4~dfsg
Import upstream version 3.4~dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/taglib/taglib/mpeg/id3v2/id3v2tag.h
 
1
/***************************************************************************
 
2
    copyright            : (C) 2002 - 2008 by Scott Wheeler
 
3
    email                : wheeler@kde.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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
 
19
 *   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_ID3V2TAG_H
 
27
#define TAGLIB_ID3V2TAG_H
 
28
 
 
29
#include "tag.h"
 
30
#include "tbytevector.h"
 
31
#include "tstring.h"
 
32
#include "tlist.h"
 
33
#include "tmap.h"
 
34
#include "taglib_export.h"
 
35
 
 
36
#include "id3v2framefactory.h"
 
37
 
 
38
namespace TagLib {
 
39
 
 
40
  class File;
 
41
 
 
42
  //! An ID3v2 implementation
 
43
 
 
44
  /*!
 
45
   * This is a relatively complete and flexible framework for working with ID3v2
 
46
   * tags.
 
47
   *
 
48
   * \see ID3v2::Tag
 
49
   */
 
50
 
 
51
  namespace ID3v2 {
 
52
 
 
53
    class Header;
 
54
    class ExtendedHeader;
 
55
    class Footer;
 
56
 
 
57
    typedef List<Frame *> FrameList;
 
58
    typedef Map<ByteVector, FrameList> FrameListMap;
 
59
 
 
60
    //! The main class in the ID3v2 implementation
 
61
 
 
62
    /*!
 
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.
 
69
     *
 
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.
 
74
     *
 
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.)
 
83
     *
 
84
     * More information on the structure of frames can be found in the ID3v2::Frame
 
85
     * class.
 
86
     *
 
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.
 
90
     *
 
91
     * \note All pointers to data structures within the tag will become invalid
 
92
     * when the tag is destroyed.
 
93
     *
 
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.
 
103
     */
 
104
 
 
105
    class TAGLIB_EXPORT Tag : public TagLib::Tag
 
106
    {
 
107
    public:
 
108
      /*!
 
109
       * Constructs an empty ID3v2 tag.
 
110
       *
 
111
       * \note You must create at least one frame for this tag to be valid.
 
112
       */
 
113
      Tag();
 
114
 
 
115
      /*!
 
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.
 
119
       *
 
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.
 
124
       *
 
125
       * \see FrameFactory
 
126
       */
 
127
      Tag(File *file, long tagOffset,
 
128
          const FrameFactory *factory = FrameFactory::instance());
 
129
 
 
130
      /*!
 
131
       * Destroys this Tag instance.
 
132
       */
 
133
      virtual ~Tag();
 
134
 
 
135
      // Reimplementations.
 
136
 
 
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;
 
144
 
 
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);
 
152
 
 
153
      virtual bool isEmpty() const;
 
154
 
 
155
      /*!
 
156
       * Returns a pointer to the tag's header.
 
157
       */
 
158
      Header *header() const;
 
159
 
 
160
      /*!
 
161
       * Returns a pointer to the tag's extended header or null if there is no
 
162
       * extended header.
 
163
       */
 
164
      ExtendedHeader *extendedHeader() const;
 
165
 
 
166
      /*!
 
167
       * Returns a pointer to the tag's footer or null if there is no footer.
 
168
       *
 
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
 
172
       * release.
 
173
       */
 
174
      Footer *footer() const;
 
175
 
 
176
      /*!
 
177
       * Returns a reference to the frame list map.  This is an FrameListMap of
 
178
       * all of the frames in the tag.
 
179
       *
 
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.
 
184
       *
 
185
       * Let's say for instance that you wanted to access the frame for total
 
186
       * beats per minute -- the TBPM frame.
 
187
       *
 
188
       * \code
 
189
       * TagLib::MPEG::File f("foo.mp3");
 
190
       *
 
191
       * // Check to make sure that it has an ID3v2 tag
 
192
       *
 
193
       * if(f.ID3v2Tag()) {
 
194
       *
 
195
       *   // Get the list of frames for a specific frame type
 
196
       *
 
197
       *   TagLib::ID3v2::FrameList l = f.ID3v2Tag()->frameListMap()["TBPM"];
 
198
       *
 
199
       *   if(!l.isEmpty())
 
200
       *     std::cout << l.front()->toString() << std::endl;
 
201
       * }
 
202
       *
 
203
       * \endcode
 
204
       *
 
205
       * \warning You should not modify this data structure directly, instead
 
206
       * use addFrame() and removeFrame().
 
207
       *
 
208
       * \see frameList()
 
209
       */
 
210
      const FrameListMap &frameListMap() const;
 
211
 
 
212
      /*!
 
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.
 
215
       *
 
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.
 
218
       *
 
219
       * \warning You should not modify this data structure directly, instead
 
220
       * use addFrame() and removeFrame().
 
221
       */
 
222
      const FrameList &frameList() const;
 
223
 
 
224
      /*!
 
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:
 
228
       *
 
229
       * \code
 
230
       * frameListMap()[frameID];
 
231
       * \endcode
 
232
       *
 
233
       * \see frameListMap()
 
234
       */
 
235
      const FrameList &frameList(const ByteVector &frameID) const;
 
236
 
 
237
      /*!
 
238
       * Add a frame to the tag.  At this point the tag takes ownership of
 
239
       * the frame and will handle freeing its memory.
 
240
       *
 
241
       * \note Using this method will invalidate any pointers on the list
 
242
       * returned by frameList()
 
243
       */
 
244
      void addFrame(Frame *frame);
 
245
 
 
246
      /*!
 
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.
 
249
       *
 
250
       * \note Using this method will invalidate any pointers on the list
 
251
       * returned by frameList()
 
252
       */
 
253
      void removeFrame(Frame *frame, bool del = true);
 
254
 
 
255
      /*!
 
256
       * Remove all frames of type \a id from the tag and free their memory.
 
257
       *
 
258
       * \note Using this method will invalidate any pointers on the list
 
259
       * returned by frameList()
 
260
       */
 
261
      void removeFrames(const ByteVector &id);
 
262
 
 
263
      /*!
 
264
       * Render the tag back to binary data, suitable to be written to disk.
 
265
       */
 
266
      ByteVector render() const;
 
267
 
 
268
    protected:
 
269
      /*!
 
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.
 
274
       */
 
275
      void read();
 
276
 
 
277
      /*!
 
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.
 
280
       */
 
281
      void parse(const ByteVector &data);
 
282
 
 
283
      /*!
 
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.
 
286
       */
 
287
      void setTextFrame(const ByteVector &id, const String &value);
 
288
 
 
289
    private:
 
290
      Tag(const Tag &);
 
291
      Tag &operator=(const Tag &);
 
292
 
 
293
      class TagPrivate;
 
294
      TagPrivate *d;
 
295
    };
 
296
 
 
297
  }
 
298
}
 
299
 
 
300
#endif