git.maemo.org Git - someplayer/blob - src/taglib/mpc/mpcfile.h

   1 /***************************************************************************
   2     copyright            : (C) 2004 by Allan Sandfeld Jensen
   3     email                : kde@carewolf.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_MPCFILE_H
  27 #define TAGLIB_MPCFILE_H
  28
  29 #include "taglib_export.h"
  30 #include "tfile.h"
  31
  32 #include "mpcproperties.h"
  33
  34 namespace TagLib {
  35
  36   class Tag;
  37
  38   namespace ID3v1 { class Tag; }
  39   namespace APE { class Tag; }
  40
  41   //! An implementation of MPC metadata
  42
  43   /*!
  44    * This is implementation of MPC metadata.
  45    *
  46    * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream
  47    * properties from the file. ID3v2 tags are invalid in MPC-files, but will be skipped
  48    * and ignored.
  49    */
  50
  51   namespace MPC {
  52
  53     //! An implementation of TagLib::File with MPC specific methods
  54
  55     /*!
  56      * This implements and provides an interface for MPC files to the
  57      * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
  58      * the abstract TagLib::File API as well as providing some additional
  59      * information specific to MPC files.
  60      * The only invalid tag combination supported is an ID3v1 tag after an APE tag.
  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 APE tags.
  78         APE     = 0x0004,
  79         //! Matches all tag types.
  80         AllTags = 0xffff
  81       };
  82
  83       /*!
  84        * Contructs an MPC 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.
  87        */
  88       File(FileName file, bool readProperties = true,
  89            Properties::ReadStyle propertiesStyle = Properties::Average);
  90
  91       /*!
  92        * Destroys this instance of the File.
  93        */
  94       virtual ~File();
  95
  96       /*!
  97        * Returns the Tag for this file.  This will be an APE tag, an ID3v1 tag
  98        * or a combination of the two.
  99        */
 100       virtual TagLib::Tag *tag() const;
 101
 102       /*!
 103        * Returns the MPC::Properties for this file.  If no audio properties
 104        * were read then this will return a null pointer.
 105        */
 106       virtual Properties *audioProperties() const;
 107
 108       /*!
 109        * Saves the file.
 110        */
 111       virtual bool save();
 112
 113       /*!
 114        * Returns a pointer to the ID3v1 tag of the file.
 115        *
 116        * If \a create is false (the default) this will return a null pointer
 117        * if there is no valid ID3v1 tag.  If \a create is true it will create
 118        * an ID3v1 tag if one does not exist. If there is already an APE tag, the
 119        * new ID3v1 tag will be placed after it.
 120        *
 121        * \note The Tag <b>is still</b> owned by the APE::File and should not be
 122        * deleted by the user.  It will be deleted when the file (object) is
 123        * destroyed.
 124        */
 125       ID3v1::Tag *ID3v1Tag(bool create = false);
 126
 127       /*!
 128        * Returns a pointer to the APE 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 APE tag.  If \a create is true it will create
 132        * a APE tag if one does not exist. If there is already an ID3v1 tag, thes
 133        * new APE tag will be placed before it.
 134        *
 135        * \note The Tag <b>is still</b> owned by the APE::File and should not be
 136        * deleted by the user.  It will be deleted when the file (object) is
 137        * destroyed.
 138        */
 139       APE::Tag *APETag(bool create = false);
 140
 141       /*!
 142        * This will remove the tags that match the OR-ed together TagTypes from the
 143        * file.  By default it removes all tags.
 144        *
 145        * \warning This will also invalidate pointers to the tags
 146        * as their memory will be freed.
 147        *
 148        * \note In order to make the removal permanent save() still needs to be called.
 149        */
 150       void strip(int tags = AllTags);
 151
 152       /*!
 153        * \deprecated
 154        * \see strip
 155        */
 156       void remove(int tags = AllTags);
 157
 158
 159     private:
 160       File(const File &);
 161       File &operator=(const File &);
 162
 163       void read(bool readProperties, Properties::ReadStyle propertiesStyle);
 164       void scan();
 165       long findAPE();
 166       long findID3v1();
 167       long findID3v2();
 168
 169       class FilePrivate;
 170       FilePrivate *d;
 171     };
 172   }
 173 }
 174
 175 #endif