/*************************************************************************** copyright : (C) 2002 - 2008 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 * * * * Alternatively, this file is available under the Mozilla Public * * License Version 1.1. You may obtain a copy of the License at * * http://www.mozilla.org/MPL/ * ***************************************************************************/ #ifndef TAGLIB_VORBISCOMMENT_H #define TAGLIB_VORBISCOMMENT_H #include "tag.h" #include "tlist.h" #include "tmap.h" #include "tstring.h" #include "tstringlist.h" #include "tbytevector.h" #include "taglib_export.h" namespace TagLib { namespace Ogg { /*! * A mapping between a list of field names, or keys, and a list of values * associated with that field. * * \see XiphComment::fieldListMap() */ typedef Map FieldListMap; //! Ogg Vorbis comment implementation /*! * This class is an implementation of the Ogg Vorbis comment specification, * to be found in section 5 of the Ogg Vorbis specification. Because this * format is also used in other (currently unsupported) Xiph.org formats, it * has been made part of a generic implementation rather than being limited * to strictly Vorbis. * * Vorbis comments are a simple vector of keys and values, called fields. * Multiple values for a given key are supported. * * \see fieldListMap() */ class TAGLIB_EXPORT XiphComment : public TagLib::Tag { public: /*! * Constructs an empty Vorbis comment. */ XiphComment(); /*! * Constructs a Vorbis comment from \a data. */ XiphComment(const ByteVector &data); /*! * Destroys this instance of the XiphComment. */ virtual ~XiphComment(); virtual String title() const; virtual String artist() const; virtual String album() const; virtual String comment() const; virtual String genre() const; virtual uint year() const; virtual uint track() const; virtual void setTitle(const String &s); virtual void setArtist(const String &s); virtual void setAlbum(const String &s); virtual void setComment(const String &s); virtual void setGenre(const String &s); virtual void setYear(uint i); virtual void setTrack(uint i); virtual bool isEmpty() const; /*! * Returns the number of fields present in the comment. */ uint fieldCount() const; /*! * Returns a reference to the map of field lists. Because Xiph comments * support multiple fields with the same key, a pure Map would not work. * As such this is a Map of string lists, keyed on the comment field name. * * The standard set of Xiph/Vorbis fields (which may or may not be * contained in any specific comment) is: * * * * For a more detailed description of these fields, please see the Ogg * Vorbis specification, section 5.2.2.1. * * \note The Ogg Vorbis comment specification does allow these key values * to be either upper or lower case. However, it is conventional for them * to be upper case. As such, TagLib, when parsing a Xiph/Vorbis comment, * converts all fields to uppercase. When you are using this data * structure, you will need to specify the field name in upper case. * * \warning You should not modify this data structure directly, instead * use addField() and removeField(). */ const FieldListMap &fieldListMap() const; /*! * Returns the vendor ID of the Ogg Vorbis encoder. libvorbis 1.0 as the * most common case always returns "Xiph.Org libVorbis I 20020717". */ String vendorID() const; /*! * Add the field specified by \a key with the data \a value. If \a replace * is true, then all of the other fields with the same key will be removed * first. * * If the field value is empty, the field will be removed. */ void addField(const String &key, const String &value, bool replace = true); /*! * Remove the field specified by \a key with the data \a value. If * \a value is null, all of the fields with the given key will be removed. */ void removeField(const String &key, const String &value = String::null); /*! * Returns true if the field is contained within the comment. * * \note This is safer than checking for membership in the FieldListMap. */ bool contains(const String &key) const; /*! * Renders the comment to a ByteVector suitable for inserting into a file. */ ByteVector render() const; // BIC: remove and merge with below /*! * Renders the comment to a ByteVector suitable for inserting into a file. * * If \a addFramingBit is true the standard Vorbis comment framing bit will * be appended. However some formats (notably FLAC) do not work with this * in place. */ ByteVector render(bool addFramingBit) const; protected: /*! * Reads the tag from the file specified in the constructor and fills the * FieldListMap. */ void parse(const ByteVector &data); private: XiphComment(const XiphComment &); XiphComment &operator=(const XiphComment &); class XiphCommentPrivate; XiphCommentPrivate *d; }; } } #endif