git.maemo.org Git - someplayer/blob - src/taglib/trueaudio/trueaudiofile.h

   1 /***************************************************************************
   2     copyright            : (C) 2006 by Lukáš Lalinský
   3     email                : lalinsky@gmail.com
   4
   5     copyright            : (C) 2004 by Allan Sandfeld Jensen
   6     email                : kde@carewolf.org
   7                            (original MPC implementation)
   8  ***************************************************************************/
   9
  10 /***************************************************************************
  11  *   This library is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the GNU Lesser General Public License version   *
  13  *   2.1 as published by the Free Software Foundation.                     *
  14  *                                                                         *
  15  *   This library is distributed in the hope that it will be useful, but   *
  16  *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
  17  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
  18  *   Lesser General Public License for more details.                       *
  19  *                                                                         *
  20  *   You should have received a copy of the GNU Lesser General Public      *
  21  *   License along with this library; if not, write to the Free Software   *
  22  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
  23  *   USA                                                                   *
  24  *                                                                         *
  25  *   Alternatively, this file is available under the Mozilla Public        *
  26  *   License Version 1.1.  You may obtain a copy of the License at         *
  27  *   http://www.mozilla.org/MPL/                                           *
  28  ***************************************************************************/
  29
  30 #ifndef TAGLIB_TRUEAUDIOFILE_H
  31 #define TAGLIB_TRUEAUDIOFILE_H
  32
  33 #include "tfile.h"
  34 #include "trueaudioproperties.h"
  35
  36 namespace TagLib {
  37
  38   class Tag;
  39
  40   namespace ID3v2 { class Tag; class FrameFactory; }
  41   namespace ID3v1 { class Tag; }
  42
  43   //! An implementation of TrueAudio metadata
  44
  45   /*!
  46    * This is implementation of TrueAudio metadata.
  47    *
  48    * This supports ID3v1 and ID3v2 tags as well as reading stream
  49    * properties from the file.
  50    */
  51
  52   namespace TrueAudio {
  53
  54     //! An implementation of TagLib::File with TrueAudio specific methods
  55
  56     /*!
  57      * This implements and provides an interface for TrueAudio files to the
  58      * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
  59      * the abstract TagLib::File API as well as providing some additional
  60      * information specific to TrueAudio files.
  61      */
  62
  63     class TAGLIB_EXPORT File : public TagLib::File
  64     {
  65     public:
  66       /*!
  67        * This set of flags is used for various operations and is suitable for
  68        * being OR-ed together.
  69        */
  70       enum TagTypes {
  71         //! Empty set.  Matches no tag types.
  72         NoTags  = 0x0000,
  73         //! Matches ID3v1 tags.
  74         ID3v1   = 0x0001,
  75         //! Matches ID3v2 tags.
  76         ID3v2   = 0x0002,
  77         //! Matches all tag types.
  78         AllTags = 0xffff
  79       };
  80
  81       /*!
  82        * Contructs an TrueAudio file from \a file.  If \a readProperties is true the
  83        * file's audio properties will also be read using \a propertiesStyle.  If
  84        * false, \a propertiesStyle is ignored.
  85        */
  86       File(FileName file, bool readProperties = true,
  87            Properties::ReadStyle propertiesStyle = Properties::Average);
  88
  89       /*!
  90        * Contructs an TrueAudio file from \a file.  If \a readProperties is true the
  91        * file's audio properties will also be read using \a propertiesStyle.  If
  92        * false, \a propertiesStyle is ignored. The frames will be created using
  93        * \a frameFactory.
  94        */
  95       File(FileName file, ID3v2::FrameFactory *frameFactory,
  96            bool readProperties = true,
  97            Properties::ReadStyle propertiesStyle = Properties::Average);
  98
  99       /*!
 100        * Destroys this instance of the File.
 101        */
 102       virtual ~File();
 103
 104       /*!
 105        * Returns the Tag for this file.
 106        */
 107       virtual TagLib::Tag *tag() const;
 108
 109       /*!
 110        * Returns the TrueAudio::Properties for this file.  If no audio properties
 111        * were read then this will return a null pointer.
 112        */
 113       virtual Properties *audioProperties() const;
 114
 115       /*!
 116        * Set the ID3v2::FrameFactory to something other than the default.
 117        *
 118        * \see ID3v2FrameFactory
 119        */
 120       void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
 121
 122       /*!
 123        * Saves the file.
 124        */
 125       virtual bool save();
 126
 127       /*!
 128        * Returns a pointer to the ID3v2 tag of the file.
 129        *
 130        * If \a create is false (the default) this will return a null pointer
 131        * if there is no valid ID3v2 tag.  If \a create is true it will create
 132        * an ID3v1 tag if one does not exist. If there is already an APE tag, the
 133        * new ID3v1 tag will be placed after it.
 134        *
 135        * \note The Tag <b>is still</b> owned by the TrueAudio::File and should not be
 136        * deleted by the user.  It will be deleted when the file (object) is
 137        * destroyed.
 138        */
 139       ID3v1::Tag *ID3v1Tag(bool create = false);
 140
 141       /*!
 142        * Returns a pointer to the ID3v1 tag of the file.
 143        *
 144        * If \a create is false (the default) this will return a null pointer
 145        * if there is no valid ID3v1 tag.  If \a create is true it will create
 146        * an ID3v1 tag if one does not exist. If there is already an APE tag, the
 147        * new ID3v1 tag will be placed after it.
 148        *
 149        * \note The Tag <b>is still</b> owned by the TrueAudio::File and should not be
 150        * deleted by the user.  It will be deleted when the file (object) is
 151        * destroyed.
 152        */
 153       ID3v2::Tag *ID3v2Tag(bool create = false);
 154
 155       /*!
 156        * This will remove the tags that match the OR-ed together TagTypes from the
 157        * file.  By default it removes all tags.
 158        *
 159        * \note This will also invalidate pointers to the tags
 160        * as their memory will be freed.
 161        * \note In order to make the removal permanent save() still needs to be called
 162        */
 163       void strip(int tags = AllTags);
 164
 165     private:
 166       File(const File &);
 167       File &operator=(const File &);
 168
 169       void read(bool readProperties, Properties::ReadStyle propertiesStyle);
 170       void scan();
 171       long findID3v1();
 172       long findID3v2();
 173
 174       class FilePrivate;
 175       FilePrivate *d;
 176     };
 177   }
 178 }
 179
 180 #endif