git.maemo.org Git - someplayer/blob - src/taglib/tag.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_TAG_H
  27 #define TAGLIB_TAG_H
  28
  29 #include "taglib_export.h"
  30 #include "tstring.h"
  31
  32 namespace TagLib {
  33
  34   //! A simple, generic interface to common audio meta data fields
  35
  36   /*!
  37    * This is an attempt to abstract away the difference in the meta data formats
  38    * of various audio codecs and tagging schemes.  As such it is generally a
  39    * subset of what is available in the specific formats but should be suitable
  40    * for most applications.  This is meant to compliment the generic APIs found
  41    * in TagLib::AudioProperties, TagLib::File and TagLib::FileRef.
  42    */
  43
  44   class TAGLIB_EXPORT Tag
  45   {
  46   public:
  47
  48     /*!
  49      * Detroys this Tag instance.
  50      */
  51     virtual ~Tag();
  52
  53     /*!
  54      * Returns the track name; if no track name is present in the tag
  55      * String::null will be returned.
  56      */
  57     virtual String title() const = 0;
  58
  59     /*!
  60      * Returns the artist name; if no artist name is present in the tag
  61      * String::null will be returned.
  62      */
  63     virtual String artist() const = 0;
  64
  65     /*!
  66      * Returns the album name; if no album name is present in the tag
  67      * String::null will be returned.
  68      */
  69     virtual String album() const = 0;
  70
  71     /*!
  72      * Returns the track comment; if no comment is present in the tag
  73      * String::null will be returned.
  74      */
  75     virtual String comment() const = 0;
  76
  77     /*!
  78      * Returns the genre name; if no genre is present in the tag String::null
  79      * will be returned.
  80      */
  81     virtual String genre() const = 0;
  82
  83     /*!
  84      * Returns the year; if there is no year set, this will return 0.
  85      */
  86     virtual uint year() const = 0;
  87
  88     /*!
  89      * Returns the track number; if there is no track number set, this will
  90      * return 0.
  91      */
  92     virtual uint track() const = 0;
  93
  94     /*!
  95      * Sets the title to \a s.  If \a s is String::null then this value will be
  96      * cleared.
  97      */
  98     virtual void setTitle(const String &s) = 0;
  99
 100     /*!
 101      * Sets the artist to \a s.  If \a s is String::null then this value will be
 102      * cleared.
 103      */
 104     virtual void setArtist(const String &s) = 0;
 105
 106     /*!
 107      * Sets the album to \a s.  If \a s is String::null then this value will be
 108      * cleared.
 109      */
 110     virtual void setAlbum(const String &s) = 0;
 111
 112     /*!
 113      * Sets the comment to \a s.  If \a s is String::null then this value will be
 114      * cleared.
 115      */
 116     virtual void setComment(const String &s) = 0;
 117
 118     /*!
 119      * Sets the genre to \a s.  If \a s is String::null then this value will be
 120      * cleared.  For tag formats that use a fixed set of genres, the appropriate
 121      * value will be selected based on a string comparison.  A list of available
 122      * genres for those formats should be available in that type's
 123      * implementation.
 124      */
 125     virtual void setGenre(const String &s) = 0;
 126
 127     /*!
 128      * Sets the year to \a i.  If \a s is 0 then this value will be cleared.
 129      */
 130     virtual void setYear(uint i) = 0;
 131
 132     /*!
 133      * Sets the track to \a i.  If \a s is 0 then this value will be cleared.
 134      */
 135     virtual void setTrack(uint i) = 0;
 136
 137     /*!
 138      * Returns true if the tag does not contain any data.  This should be
 139      * reimplemented in subclasses that provide more than the basic tagging
 140      * abilities in this class.
 141      */
 142     virtual bool isEmpty() const;
 143
 144     /*!
 145      * Copies the generic data from one tag to another.
 146      *
 147      * \note This will no affect any of the lower level details of the tag.  For
 148      * instance if any of the tag type specific data (maybe a URL for a band) is
 149      * set, this will not modify or copy that.  This just copies using the API
 150      * in this class.
 151      *
 152      * If \a overwrite is true then the values will be unconditionally copied.
 153      * If false only empty values will be overwritten.
 154      */
 155     static void duplicate(const Tag *source, Tag *target, bool overwrite = true);
 156
 157   protected:
 158     /*!
 159      * Construct a Tag.  This is protected since tags should only be instantiated
 160      * through subclasses.
 161      */
 162     Tag();
 163
 164   private:
 165     Tag(const Tag &);
 166     Tag &operator=(const Tag &);
 167
 168     class TagPrivate;
 169     TagPrivate *d;
 170   };
 171 }
 172
 173 #endif