git.maemo.org Git - someplayer/blob - src/taglib/mpeg/id3v2/id3v2header.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_ID3V2HEADER_H
  27 #define TAGLIB_ID3V2HEADER_H
  28
  29 #include "tbytevector.h"
  30 #include "taglib_export.h"
  31
  32 namespace TagLib {
  33
  34   namespace ID3v2 {
  35
  36     //! An implementation of ID3v2 headers
  37
  38     /*!
  39      * This class implements ID3v2 headers.  It attempts to follow, both
  40      * semantically and programatically, the structure specified in
  41      * the ID3v2 standard.  The API is based on the properties of ID3v2 headers
  42      * specified there.  If any of the terms used in this documentation are
  43      * unclear please check the specification in the linked section.
  44      * (Structure, <a href="id3v2-structure.html#3.1">3.1</a>)
  45      */
  46
  47     class TAGLIB_EXPORT Header
  48     {
  49     public:
  50       /*!
  51        * Constructs an empty ID3v2 header.
  52        */
  53       Header();
  54
  55       /*!
  56        * Constructs an ID3v2 header based on \a data.  parse() is called
  57        * immediately.
  58        */
  59       Header(const ByteVector &data);
  60
  61       /*!
  62        * Destroys the header.
  63        */
  64       virtual ~Header();
  65
  66       /*!
  67        * Returns the major version number.  (Note: This is the 4, not the 2 in
  68        * ID3v2.4.0.  The 2 is implied.)
  69        */
  70       uint majorVersion() const;
  71
  72       /*!
  73        * Set the the major version number to \a version.  (Note: This is
  74        * the 4, not the 2 in ID3v2.4.0.  The 2 is implied.)
  75        * \see majorVersion()
  76        *
  77        * \note This is used by the internal parser; this will not change the
  78        * version which is written and in general should not be called by API
  79        * users.
  80        */
  81       void setMajorVersion(uint version);
  82
  83       /*!
  84        * Returns the revision number.  (Note: This is the 0, not the 4 in
  85        * ID3v2.4.0.  The 2 is implied.)
  86        */
  87       uint revisionNumber() const;
  88
  89       /*!
  90        * Returns true if unsynchronisation has been applied to all frames.
  91        */
  92       bool unsynchronisation() const;
  93
  94       /*!
  95        * Returns true if an extended header is present in the tag.
  96        */
  97       bool extendedHeader() const;
  98
  99       /*!
 100        * Returns true if the experimental indicator flag is set.
 101        */
 102       bool experimentalIndicator() const;
 103
 104       /*!
 105        * Returns true if a footer is present in the tag.
 106        */
 107       bool footerPresent() const;
 108       /*!
 109        * Returns the tag size in bytes.  This is the size of the frame content.
 110        * The size of the \e entire tag will be this plus the header size (10
 111        * bytes) and, if present, the footer size (potentially another 10 bytes).
 112        *
 113        * \note This is the value as read from the header to which TagLib attempts
 114        * to provide an API to; it was not a design decision on the part of TagLib
 115        * to not include the mentioned portions of the tag in the \e size.
 116        *
 117        * \see completeTagSize()
 118        */
 119       uint tagSize() const;
 120
 121       /*!
 122        * Returns the tag size, including the header and, if present, the footer
 123        * size.
 124        *
 125        * \see tagSize()
 126        */
 127       uint completeTagSize() const;
 128
 129       /*!
 130        * Set the tag size to \a s.
 131        * \see tagSize()
 132        */
 133       void setTagSize(uint s);
 134
 135       /*!
 136        * Returns the size of the header.  Presently this is always 10 bytes.
 137        */
 138       static uint size();
 139
 140       /*!
 141        * Returns the string used to identify and ID3v2 tag inside of a file.
 142        * Presently this is always "ID3".
 143        */
 144       static ByteVector fileIdentifier();
 145
 146       /*!
 147        * Sets the data that will be used as the header.  10 bytes, starting from
 148        * the beginning of \a data are used.
 149        */
 150       void setData(const ByteVector &data);
 151
 152       /*!
 153        * Renders the Header back to binary format.
 154        */
 155       ByteVector render() const;
 156
 157     protected:
 158       /*!
 159        * Called by setData() to parse the header data.  It makes this information
 160        * available through the public API.
 161        */
 162       void parse(const ByteVector &data);
 163
 164     private:
 165       Header(const Header &);
 166       Header &operator=(const Header &);
 167
 168       class HeaderPrivate;
 169       HeaderPrivate *d;
 170     };
 171
 172   }
 173 }
 174
 175 #endif