git.maemo.org Git - someplayer/blob - src/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