This commit was manufactured by cvs2svn to accommodate

a server-side copy/move.


git-svn-id: svn://anonsvn.kde.org/home/kde/trunk/kdesupport/taglib@288617 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

tag.h

@@ -0,0 +1,168 @@
+/***************************************************************************
+    copyright            : (C) 2003 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it  under the terms of the GNU Lesser General Public License version  *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ ***************************************************************************/
+
+#ifndef TAGLIB_TAG_H
+#define TAGLIB_TAG_H
+
+#include <tstring.h>
+
+namespace TagLib {
+
+  //! A simple, generic interface to common audio meta data fields
+
+  /*!
+   * This is an attempt to abstract away the difference in the meta data formats
+   * of various audio codecs and tagging schemes.  As such it is generally a
+   * subset of what is available in the specific formats but should be suitable
+   * for most applications.  This is meant to complient the generic APIs found
+   * in TagLib::AudioProperties, TagLib::File and TagLib::FileRef.
+   */
+
+  class Tag
+  {
+  public:
+
+    /*!
+     * Detroys this Tag instance.
+     */
+    virtual ~Tag();
+
+    /*!
+     * Returns the track name; if no track name is present in the tag
+     * String::null will be returned.
+     */
+    virtual String title() const = 0;
+
+    /*!
+     * Returns the artist name; if no artist name is present in the tag
+     * String::null will be returned.
+     */
+    virtual String artist() const = 0;
+
+    /*!
+     * Returns the album name; if no album name is present in the tag
+     * String::null will be returned.
+     */
+    virtual String album() const = 0;
+
+    /*!
+     * Returns the track comment; if no comment is present in the tag
+     * String::null will be returned.
+     */
+    virtual String comment() const = 0;
+
+    /*!
+     * Returns the genre name; if no genre is present in the tag String::null
+     * will be returned.
+     */
+    virtual String genre() const = 0;
+
+    /*!
+     * Returns the year; if there is no year set, this will return 0.
+     */
+    virtual uint year() const = 0;
+
+    /*!
+     * Returns the track number; if there is no track number set, this will
+     * return 0.
+     */
+    virtual uint track() const = 0;
+
+    /*!
+     * Sets the title to \a s.  If \a s is String::null then this value will be
+     * cleared.
+     */
+    virtual void setTitle(const String &s) = 0;
+
+    /*!
+     * Sets the artist to \a s.  If \a s is String::null then this value will be
+     * cleared.
+     */
+    virtual void setArtist(const String &s) = 0;
+
+    /*!
+     * Sets the album to \a s.  If \a s is String::null then this value will be
+     * cleared.
+     */
+    virtual void setAlbum(const String &s) = 0;
+
+    /*!
+     * Sets the album to \a s.  If \a s is String::null then this value will be
+     * cleared.
+     */
+    virtual void setComment(const String &s) = 0;
+
+    /*!
+     * Sets the genre to \a s.  If \a s is String::null then this value will be
+     * cleared.  For tag formats that use a fixed set of genres, the appropriate
+     * value will be selected based on a string comparison.  A list of available
+     * genres for those formats should be available in that type's
+     * implementation.
+     */
+    virtual void setGenre(const String &s) = 0;
+
+    /*!
+     * Sets the year to \a i.  If \a s is 0 then this value will be cleared.
+     */
+    virtual void setYear(uint i) = 0;
+
+    /*!
+     * Sets the track to \a i.  If \a s is 0 then this value will be cleared.
+     */
+    virtual void setTrack(uint i) = 0;
+
+    /*!
+     * Returns true if the tag does not contain any data.  This should be
+     * reimplemented in subclasses that provide more than the basic tagging
+     * abilities in this class.
+     */
+    virtual bool isEmpty() const;
+
+    /*!
+     * Copies the generic data from one tag to another.
+     *
+     * \note This will no affect any of the lower level details of the tag.  For
+     * instance if any of the tag type specific data (maybe a URL for a band) is
+     * set, this will not modify or copy that.  This just copies using the API
+     * in this class.
+     *
+     * If \a overwrite is true then the values will be unconditionally copied.
+     * If false only empty values will be overwritten.
+     */
+    static void duplicate(const Tag *source, Tag *target, bool overwrite = true);
+
+  protected:
+    /*!
+     * Construct a Tag.  This is protected since tags should only be instantiated
+     * through subclasses.
+     */
+    Tag();
+
+  private:
+    Tag(const Tag &);
+    Tag &operator=(const Tag &);
+
+    class TagPrivate;
+    TagPrivate *d;
+  };
+}
+
+#endif