vcs.maemo.org Git - someplayer/blob - src/taglib/mpeg/mpegfile.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_MPEGFILE_H
  27 #define TAGLIB_MPEGFILE_H
  28
  29 #include "taglib_export.h"
  30 #include "tfile.h"
  31
  32 #include "mpegproperties.h"
  33
  34 namespace TagLib {
  35
  36   namespace ID3v2 { class Tag; class FrameFactory; }
  37   namespace ID3v1 { class Tag; }
  38   namespace APE { class Tag; }
  39
  40   //! An implementation of TagLib::File with MPEG (MP3) specific methods
  41
  42   namespace MPEG {
  43
  44     //! An MPEG file class with some useful methods specific to MPEG
  45
  46     /*!
  47      * This implements the generic TagLib::File API and additionally provides
  48      * access to properties that are distinct to MPEG files, notably access
  49      * to the different ID3 tags.
  50      */
  51
  52     class TAGLIB_EXPORT File : public TagLib::File
  53     {
  54     public:
  55       /*!
  56        * This set of flags is used for various operations and is suitable for
  57        * being OR-ed together.
  58        */
  59       enum TagTypes {
  60         //! Empty set.  Matches no tag types.
  61         NoTags  = 0x0000,
  62         //! Matches ID3v1 tags.
  63         ID3v1   = 0x0001,
  64         //! Matches ID3v2 tags.
  65         ID3v2   = 0x0002,
  66         //! Matches APE tags.
  67         APE     = 0x0004,
  68         //! Matches all tag types.
  69         AllTags = 0xffff
  70       };
  71
  72       /*!
  73        * Contructs an MPEG file from \a file.  If \a readProperties is true the
  74        * file's audio properties will also be read using \a propertiesStyle.  If
  75        * false, \a propertiesStyle is ignored.
  76        *
  77        * \deprecated This constructor will be dropped in favor of the one below
  78        * in a future version.
  79        */
  80       File(FileName file, bool readProperties = true,
  81            Properties::ReadStyle propertiesStyle = Properties::Average);
  82
  83       /*!
  84        * Contructs an MPEG file from \a file.  If \a readProperties is true the
  85        * file's audio properties will also be read using \a propertiesStyle.  If
  86        * false, \a propertiesStyle is ignored.  The frames will be created using
  87        * \a frameFactory.
  88        */
  89       // BIC: merge with the above constructor
  90       File(FileName file, ID3v2::FrameFactory *frameFactory,
  91            bool readProperties = true,
  92            Properties::ReadStyle propertiesStyle = Properties::Average);
  93
  94       /*!
  95        * Destroys this instance of the File.
  96        */
  97       virtual ~File();
  98
  99       /*!
 100        * Returns a pointer to a tag that is the union of the ID3v2 and ID3v1
 101        * tags. The ID3v2 tag is given priority in reading the information -- if
 102        * requested information exists in both the ID3v2 tag and the ID3v1 tag,
 103        * the information from the ID3v2 tag will be returned.
 104        *
 105        * If you would like more granular control over the content of the tags,
 106        * with the concession of generality, use the tag-type specific calls.
 107        *
 108        * \note As this tag is not implemented as an ID3v2 tag or an ID3v1 tag,
 109        * but a union of the two this pointer may not be cast to the specific
 110        * tag types.
 111        *
 112        * \see ID3v1Tag()
 113        * \see ID3v2Tag()
 114        * \see APETag()
 115        */
 116       virtual Tag *tag() const;
 117
 118       /*!
 119        * Returns the MPEG::Properties for this file.  If no audio properties
 120        * were read then this will return a null pointer.
 121        */
 122       virtual Properties *audioProperties() const;
 123
 124       /*!
 125        * Save the file.  If at least one tag -- ID3v1 or ID3v2 -- exists this
 126        * will duplicate its content into the other tag.  This returns true
 127        * if saving was successful.
 128        *
 129        * If neither exists or if both tags are empty, this will strip the tags
 130        * from the file.
 131        *
 132        * This is the same as calling save(AllTags);
 133        *
 134        * If you would like more granular control over the content of the tags,
 135        * with the concession of generality, use paramaterized save call below.
 136        *
 137        * \see save(int tags)
 138        */
 139       virtual bool save();
 140
 141       /*!
 142        * Save the file.  This will attempt to save all of the tag types that are
 143        * specified by OR-ing together TagTypes values.  The save() method above
 144        * uses AllTags.  This returns true if saving was successful.
 145        *
 146        * This strips all tags not included in the mask, but does not modify them
 147        * in memory, so later calls to save() which make use of these tags will
 148        * remain valid.  This also strips empty tags.
 149        */
 150       bool save(int tags);
 151
 152       /*!
 153        * Save the file.  This will attempt to save all of the tag types that are
 154        * specified by OR-ing together TagTypes values.  The save() method above
 155        * uses AllTags.  This returns true if saving was successful.
 156        *
 157        * If \a stripOthers is true this strips all tags not included in the mask,
 158        * but does not modify them in memory, so later calls to save() which make
 159        * use of these tags will remain valid.  This also strips empty tags.
 160        */
 161       // BIC: combine with the above method
 162       bool save(int tags, bool stripOthers);
 163
 164       /*!
 165        * Returns a pointer to the ID3v2 tag of the file.
 166        *
 167        * If \a create is false (the default) this will return a null pointer
 168        * if there is no valid ID3v2 tag.  If \a create is true it will create
 169        * an ID3v2 tag if one does not exist.
 170        *
 171        * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
 172        * deleted by the user.  It will be deleted when the file (object) is
 173        * destroyed.
 174        */
 175       ID3v2::Tag *ID3v2Tag(bool create = false);
 176
 177       /*!
 178        * Returns a pointer to the ID3v1 tag of the file.
 179        *
 180        * If \a create is false (the default) this will return a null pointer
 181        * if there is no valid ID3v1 tag.  If \a create is true it will create
 182        * an ID3v1 tag if one does not exist.
 183        *
 184        * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
 185        * deleted by the user.  It will be deleted when the file (object) is
 186        * destroyed.
 187        */
 188       ID3v1::Tag *ID3v1Tag(bool create = false);
 189
 190       /*!
 191        * Returns a pointer to the APE tag of the file.
 192        *
 193        * If \a create is false (the default) this will return a null pointer
 194        * if there is no valid APE tag.  If \a create is true it will create
 195        * an APE tag if one does not exist.
 196        *
 197        * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
 198        * deleted by the user.  It will be deleted when the file (object) is
 199        * destroyed.
 200        */
 201       APE::Tag *APETag(bool create = false);
 202
 203       /*!
 204        * This will strip the tags that match the OR-ed together TagTypes from the
 205        * file.  By default it strips all tags.  It returns true if the tags are
 206        * successfully stripped.
 207        *
 208        * This is equivalent to strip(tags, true)
 209        *
 210        * \note This will also invalidate pointers to the ID3 and APE tags
 211        * as their memory will be freed.
 212        */
 213       bool strip(int tags = AllTags);
 214
 215       /*!
 216        * This will strip the tags that match the OR-ed together TagTypes from the
 217        * file.  By default it strips all tags.  It returns true if the tags are
 218        * successfully stripped.
 219        *
 220        * If \a freeMemory is true the ID3 and APE tags will be deleted and
 221        * pointers to them will be invalidated.
 222        */
 223       // BIC: merge with the method above
 224       bool strip(int tags, bool freeMemory);
 225
 226       /*!
 227        * Set the ID3v2::FrameFactory to something other than the default.
 228        *
 229        * \see ID3v2FrameFactory
 230        */
 231       void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
 232
 233       /*!
 234        * Returns the position in the file of the first MPEG frame.
 235        */
 236       long firstFrameOffset();
 237
 238       /*!
 239        * Returns the position in the file of the next MPEG frame,
 240        * using the current position as start
 241        */
 242       long nextFrameOffset(long position);
 243
 244       /*!
 245        * Returns the position in the file of the previous MPEG frame,
 246        * using the current position as start
 247        */
 248       long previousFrameOffset(long position);
 249
 250       /*!
 251        * Returns the position in the file of the last MPEG frame.
 252        */
 253       long lastFrameOffset();
 254
 255     private:
 256       File(const File &);
 257       File &operator=(const File &);
 258
 259       void read(bool readProperties, Properties::ReadStyle propertiesStyle);
 260       long findID3v2();
 261       long findID3v1();
 262       void findAPE();
 263
 264       /*!
 265        * MPEG frames can be recognized by the bit pattern 11111111 111, so the
 266        * first byte is easy to check for, however checking to see if the second byte
 267        * starts with \e 111 is a bit more tricky, hence this member function.
 268        */
 269       static bool secondSynchByte(char byte);
 270
 271       class FilePrivate;
 272       FilePrivate *d;
 273     };
 274   }
 275 }
 276
 277 #endif