src/metadata/trueaudio/ttafile.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., 51 Franklin Street, Fifth Floor, Boston,            *
  23  *   MA  02110-1301  USA                                                   *
  24  ***************************************************************************/
  25
  26 #ifndef TAGLIB_TTAFILE_H
  27 #define TAGLIB_TTAFILE_H
  28
  29 #include "../tfile_helper.h"
  30
  31 #include "ttaproperties.h"
  32
  33 namespace TagLib {
  34
  35   class Tag;
  36
  37   namespace ID3v2 { class Tag; class FrameFactory; }
  38   namespace ID3v1 { class Tag; }
  39
  40   //! An implementation of TTA metadata
  41
  42   /*!
  43    * This is implementation of TTA metadata.
  44    *
  45    * This supports ID3v1 and ID3v2 tags as well as reading stream
  46    * properties from the file.
  47    */
  48
  49   namespace TTA {
  50
  51     //! An implementation of TagLib::File with TTA specific methods
  52
  53     /*!
  54      * This implements and provides an interface for TTA files to the
  55      * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
  56      * the abstract TagLib::File API as well as providing some additional
  57      * information specific to TTA files.
  58      */
  59
  60     class File : public TagLib::File
  61     {
  62     public:
  63       /*!
  64        * This set of flags is used for various operations and is suitable for
  65        * being OR-ed together.
  66        */
  67       enum TagTypes {
  68         //! Empty set.  Matches no tag types.
  69         NoTags  = 0x0000,
  70         //! Matches ID3v1 tags.
  71         ID3v1   = 0x0001,
  72         //! Matches ID3v2 tags.
  73         ID3v2   = 0x0002,
  74         //! Matches all tag types.
  75         AllTags = 0xffff
  76       };
  77
  78       /*!
  79        * Contructs an MPC file from \a file.  If \a readProperties is true the
  80        * file's audio properties will also be read using \a propertiesStyle.  If
  81        * false, \a propertiesStyle is ignored.
  82        */
  83       explicit File(TagLibFileName file, bool readProperties = true,
  84            Properties::ReadStyle propertiesStyle = Properties::Average);
  85
  86       /*!
  87        * Contructs an MPC file from \a file.  If \a readProperties is true the
  88        * file's audio properties will also be read using \a propertiesStyle.  If
  89        * false, \a propertiesStyle is ignored. The frames will be created using
  90        * \a frameFactory.
  91        */
  92       File(TagLibFileName file, ID3v2::FrameFactory *frameFactory,
  93            bool readProperties = true,
  94            Properties::ReadStyle propertiesStyle = Properties::Average);
  95
  96       /*!
  97        * Destroys this instance of the File.
  98        */
  99       virtual ~File();
 100
 101       /*!
 102        * Returns the Tag for this file.  This will be an APE tag, an ID3v1 tag
 103        * or a combination of the two.
 104        */
 105       virtual TagLib::Tag *tag() const;
 106
 107       /*!
 108        * Returns the MPC::Properties for this file.  If no audio properties
 109        * were read then this will return a null pointer.
 110        */
 111       virtual Properties *audioProperties() const;
 112
 113       /*!
 114        * Set the ID3v2::FrameFactory to something other than the default.
 115        *
 116        * \see ID3v2FrameFactory
 117        */
 118       void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
 119
 120       /*!
 121        * Saves the file.
 122        */
 123       virtual bool save();
 124
 125       /*!
 126        * Returns a pointer to the ID3v2 tag of the file.
 127        *
 128        * If \a create is false (the default) this will return a null pointer
 129        * if there is no valid ID3v2 tag.  If \a create is true it will create
 130        * an ID3v1 tag if one does not exist. If there is already an APE tag, the
 131        * new ID3v1 tag will be placed after it.
 132        *
 133        * \note The Tag <b>is still</b> owned by the TTA::File and should not be
 134        * deleted by the user.  It will be deleted when the file (object) is
 135        * destroyed.
 136        */
 137       ID3v1::Tag *ID3v1Tag(bool create = false);
 138
 139       /*!
 140        * Returns a pointer to the ID3v1 tag of the file.
 141        *
 142        * If \a create is false (the default) this will return a null pointer
 143        * if there is no valid ID3v1 tag.  If \a create is true it will create
 144        * an ID3v1 tag if one does not exist. If there is already an APE tag, the
 145        * new ID3v1 tag will be placed after it.
 146        *
 147        * \note The Tag <b>is still</b> owned by the TTA::File and should not be
 148        * deleted by the user.  It will be deleted when the file (object) is
 149        * destroyed.
 150        */
 151       ID3v2::Tag *ID3v2Tag(bool create = false);
 152
 153       /*!
 154        * This will remove the tags that match the OR-ed together TagTypes from the
 155        * file.  By default it removes all tags.
 156        *
 157        * \note This will also invalidate pointers to the tags
 158        * as their memory will be freed.
 159        * \note In order to make the removal permanent save() still needs to be called
 160        */
 161       void remove(int tags = AllTags);
 162
 163     private:
 164       File(const File &);
 165       File &operator=(const File &);
 166
 167       void read(bool readProperties, Properties::ReadStyle propertiesStyle);
 168       void scan();
 169       long findID3v1();
 170       long findID3v2();
 171
 172       class FilePrivate;
 173       FilePrivate *d;
 174     };
 175   }
 176 }
 177
 178 #endif