git.maemo.org Git - someplayer/blob - src/taglib/ogg/xiphcomment.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_VORBISCOMMENT_H
  27 #define TAGLIB_VORBISCOMMENT_H
  28
  29 #include "tag.h"
  30 #include "tlist.h"
  31 #include "tmap.h"
  32 #include "tstring.h"
  33 #include "tstringlist.h"
  34 #include "tbytevector.h"
  35 #include "taglib_export.h"
  36
  37 namespace TagLib {
  38
  39   namespace Ogg {
  40
  41     /*!
  42      * A mapping between a list of field names, or keys, and a list of values
  43      * associated with that field.
  44      *
  45      * \see XiphComment::fieldListMap()
  46      */
  47     typedef Map<String, StringList> FieldListMap;
  48
  49     //! Ogg Vorbis comment implementation
  50
  51     /*!
  52      * This class is an implementation of the Ogg Vorbis comment specification,
  53      * to be found in section 5 of the Ogg Vorbis specification.  Because this
  54      * format is also used in other (currently unsupported) Xiph.org formats, it
  55      * has been made part of a generic implementation rather than being limited
  56      * to strictly Vorbis.
  57      *
  58      * Vorbis comments are a simple vector of keys and values, called fields.
  59      * Multiple values for a given key are supported.
  60      *
  61      * \see fieldListMap()
  62      */
  63
  64     class TAGLIB_EXPORT XiphComment : public TagLib::Tag
  65     {
  66     public:
  67       /*!
  68        * Constructs an empty Vorbis comment.
  69        */
  70       XiphComment();
  71
  72       /*!
  73        * Constructs a Vorbis comment from \a data.
  74        */
  75       XiphComment(const ByteVector &data);
  76
  77       /*!
  78        * Destroys this instance of the XiphComment.
  79        */
  80       virtual ~XiphComment();
  81
  82       virtual String title() const;
  83       virtual String artist() const;
  84       virtual String album() const;
  85       virtual String comment() const;
  86       virtual String genre() const;
  87       virtual uint year() const;
  88       virtual uint track() const;
  89
  90       virtual void setTitle(const String &s);
  91       virtual void setArtist(const String &s);
  92       virtual void setAlbum(const String &s);
  93       virtual void setComment(const String &s);
  94       virtual void setGenre(const String &s);
  95       virtual void setYear(uint i);
  96       virtual void setTrack(uint i);
  97
  98       virtual bool isEmpty() const;
  99
 100       /*!
 101        * Returns the number of fields present in the comment.
 102        */
 103       uint fieldCount() const;
 104
 105       /*!
 106        * Returns a reference to the map of field lists.  Because Xiph comments
 107        * support multiple fields with the same key, a pure Map would not work.
 108        * As such this is a Map of string lists, keyed on the comment field name.
 109        *
 110        * The standard set of Xiph/Vorbis fields (which may or may not be
 111        * contained in any specific comment) is:
 112        *
 113        * <ul>
 114        *   <li>TITLE</li>
 115        *   <li>VERSION</li>
 116        *   <li>ALBUM</li>
 117        *   <li>ARTIST</li>
 118        *   <li>PERFORMER</li>
 119        *   <li>COPYRIGHT</li>
 120        *   <li>ORGANIZATION</li>
 121        *   <li>DESCRIPTION</li>
 122        *   <li>GENRE</li>
 123        *   <li>DATE</li>
 124        *   <li>LOCATION</li>
 125        *   <li>CONTACT</li>
 126        *   <li>ISRC</li>
 127        * </ul>
 128        *
 129        * For a more detailed description of these fields, please see the Ogg
 130        * Vorbis specification, section 5.2.2.1.
 131        *
 132        * \note The Ogg Vorbis comment specification does allow these key values
 133        * to be either upper or lower case.  However, it is conventional for them
 134        * to be upper case.  As such, TagLib, when parsing a Xiph/Vorbis comment,
 135        * converts all fields to uppercase.  When you are using this data
 136        * structure, you will need to specify the field name in upper case.
 137        *
 138        * \warning You should not modify this data structure directly, instead
 139        * use addField() and removeField().
 140        */
 141       const FieldListMap &fieldListMap() const;
 142
 143       /*!
 144        * Returns the vendor ID of the Ogg Vorbis encoder.  libvorbis 1.0 as the
 145        * most common case always returns "Xiph.Org libVorbis I 20020717".
 146        */
 147       String vendorID() const;
 148
 149       /*!
 150        * Add the field specified by \a key with the data \a value.  If \a replace
 151        * is true, then all of the other fields with the same key will be removed
 152        * first.
 153        *
 154        * If the field value is empty, the field will be removed.
 155        */
 156       void addField(const String &key, const String &value, bool replace = true);
 157
 158       /*!
 159        * Remove the field specified by \a key with the data \a value.  If
 160        * \a value is null, all of the fields with the given key will be removed.
 161        */
 162       void removeField(const String &key, const String &value = String::null);
 163
 164       /*!
 165        * Returns true if the field is contained within the comment.
 166        *
 167        * \note This is safer than checking for membership in the FieldListMap.
 168        */
 169       bool contains(const String &key) const;
 170
 171       /*!
 172        * Renders the comment to a ByteVector suitable for inserting into a file.
 173        */
 174       ByteVector render() const; // BIC: remove and merge with below
 175
 176       /*!
 177        * Renders the comment to a ByteVector suitable for inserting into a file.
 178        *
 179        * If \a addFramingBit is true the standard Vorbis comment framing bit will
 180        * be appended.  However some formats (notably FLAC) do not work with this
 181        * in place.
 182        */
 183       ByteVector render(bool addFramingBit) const;
 184
 185     protected:
 186       /*!
 187        * Reads the tag from the file specified in the constructor and fills the
 188        * FieldListMap.
 189        */
 190       void parse(const ByteVector &data);
 191
 192     private:
 193       XiphComment(const XiphComment &);
 194       XiphComment &operator=(const XiphComment &);
 195
 196       class XiphCommentPrivate;
 197       XiphCommentPrivate *d;
 198     };
 199   }
 200 }
 201
 202 #endif