1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : [email protected] 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., 51 Franklin Street, Fifth Floor, Boston, MA * 19 * 02110-1301 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 PropertyMap; 45 46 class TAGLIB_EXPORT Tag 47 { 48 public: 49 50 /*! 51 * Destroys this Tag instance. 52 */ 53 virtual ~Tag(); 54 55 /*! 56 * Exports the tags of the file as dictionary mapping (human readable) tag 57 * names (Strings) to StringLists of tag values. 58 * The default implementation in this class considers only the usual built-in 59 * tags (artist, album, ...) and only one value per key. 60 */ 61 PropertyMap properties() const; 62 63 /*! 64 * Removes unsupported properties, or a subset of them, from the tag. 65 * The parameter \a properties must contain only entries from 66 * properties().unsupportedData(). 67 * BIC: Will become virtual in future releases. Currently the non-virtual 68 * standard implementation of TagLib::Tag does nothing, since there are 69 * no unsupported elements. 70 */ 71 void removeUnsupportedProperties(const StringList& properties); 72 73 /*! 74 * Sets the tags of this File to those specified in \a properties. This default 75 * implementation sets only the tags for which setter methods exist in this class 76 * (artist, album, ...), and only one value per key; the rest will be contained 77 * in the returned PropertyMap. 78 */ 79 PropertyMap setProperties(const PropertyMap &properties); 80 81 /*! 82 * Returns the track name; if no track name is present in the tag 83 * String::null will be returned. 84 */ 85 virtual String title() const = 0; 86 87 /*! 88 * Returns the artist name; if no artist name is present in the tag 89 * String::null will be returned. 90 */ 91 virtual String artist() const = 0; 92 93 /*! 94 * Returns the album name; if no album name is present in the tag 95 * String::null will be returned. 96 */ 97 virtual String album() const = 0; 98 99 /*! 100 * Returns the track comment; if no comment is present in the tag 101 * String::null will be returned. 102 */ 103 virtual String comment() const = 0; 104 105 /*! 106 * Returns the genre name; if no genre is present in the tag String::null 107 * will be returned. 108 */ 109 virtual String genre() const = 0; 110 111 /*! 112 * Returns the year; if there is no year set, this will return 0. 113 */ 114 virtual unsigned int year() const = 0; 115 116 /*! 117 * Returns the track number; if there is no track number set, this will 118 * return 0. 119 */ 120 virtual unsigned int track() const = 0; 121 122 /*! 123 * Sets the title to \a s. If \a s is String::null then this value will be 124 * cleared. 125 */ 126 virtual void setTitle(const String &s) = 0; 127 128 /*! 129 * Sets the artist to \a s. If \a s is String::null then this value will be 130 * cleared. 131 */ 132 virtual void setArtist(const String &s) = 0; 133 134 /*! 135 * Sets the album to \a s. If \a s is String::null then this value will be 136 * cleared. 137 */ 138 virtual void setAlbum(const String &s) = 0; 139 140 /*! 141 * Sets the comment to \a s. If \a s is String::null then this value will be 142 * cleared. 143 */ 144 virtual void setComment(const String &s) = 0; 145 146 /*! 147 * Sets the genre to \a s. If \a s is String::null then this value will be 148 * cleared. For tag formats that use a fixed set of genres, the appropriate 149 * value will be selected based on a string comparison. A list of available 150 * genres for those formats should be available in that type's 151 * implementation. 152 */ 153 virtual void setGenre(const String &s) = 0; 154 155 /*! 156 * Sets the year to \a i. If \a s is 0 then this value will be cleared. 157 */ 158 virtual void setYear(unsigned int i) = 0; 159 160 /*! 161 * Sets the track to \a i. If \a s is 0 then this value will be cleared. 162 */ 163 virtual void setTrack(unsigned int i) = 0; 164 165 /*! 166 * Returns true if the tag does not contain any data. This should be 167 * reimplemented in subclasses that provide more than the basic tagging 168 * abilities in this class. 169 */ 170 virtual bool isEmpty() const; 171 172 /*! 173 * Copies the generic data from one tag to another. 174 * 175 * \note This will no affect any of the lower level details of the tag. For 176 * instance if any of the tag type specific data (maybe a URL for a band) is 177 * set, this will not modify or copy that. This just copies using the API 178 * in this class. 179 * 180 * If \a overwrite is true then the values will be unconditionally copied. 181 * If false only empty values will be overwritten. 182 */ 183 static void duplicate(const Tag *source, Tag *target, bool overwrite = true); 184 185 protected: 186 /*! 187 * Construct a Tag. This is protected since tags should only be instantiated 188 * through subclasses. 189 */ 190 Tag(); 191 192 private: 193 Tag(const Tag &); 194 Tag &operator=(const Tag &); 195 196 class TagPrivate; 197 TagPrivate *d; 198 }; 199 } 200 201 #endif 202