1 /*************************************************************************** 2 copyright : (C) 2012 by Michael Helmling 3 email : helmling@mathematik.uni-kl.de 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_PROPERTYMAP_H_ 27 #define TAGLIB_PROPERTYMAP_H_ 28 29 #include "tmap.h" 30 #include "tstringlist.h" 31 32 namespace TagLib { 33 34 typedef Map<String,StringList> SimplePropertyMap; 35 36 //! A map for format-independent <key,valuelist> tag representations. 37 38 /*! 39 * This map implements a generic representation of textual audio metadata 40 * ("tags") realized as pairs of a case-insensitive key 41 * and a nonempty list of corresponding values, each value being an arbitrary 42 * unicode String. 43 * 44 * Note that most metadata formats pose additional conditions on the tag keys. The 45 * most popular ones (Vorbis, APE, ID3v2) should support all ASCII only words of 46 * length between 2 and 16. 47 * 48 * This class can contain any tags, but here is a list of "well-known" tags that 49 * you might want to use: 50 * 51 * Basic tags: 52 * 53 * - TITLE 54 * - ALBUM 55 * - ARTIST 56 * - ALBUMARTIST 57 * - SUBTITLE 58 * - TRACKNUMBER 59 * - DISCNUMBER 60 * - DATE 61 * - ORIGINALDATE 62 * - GENRE 63 * - COMMENT 64 * 65 * Sort names: 66 * 67 * - TITLESORT 68 * - ALBUMSORT 69 * - ARTISTSORT 70 * - ALBUMARTISTSORT 71 * 72 * Credits: 73 * 74 * - COMPOSER 75 * - LYRICIST 76 * - CONDUCTOR 77 * - REMIXER 78 * - PERFORMER:<XXXX> 79 * 80 * Other tags: 81 * 82 * - ISRC 83 * - ASIN 84 * - BPM 85 * - COPYRIGHT 86 * - ENCODEDBY 87 * - MOOD 88 * - COMMENT 89 * - MEDIA 90 * - LABEL 91 * - CATALOGNUMBER 92 * - BARCODE 93 * 94 * MusicBrainz identifiers: 95 * 96 * - MUSICBRAINZ_TRACKID 97 * - MUSICBRAINZ_ALBUMID 98 * - MUSICBRAINZ_RELEASEGROUPID 99 * - MUSICBRAINZ_WORKID 100 * - MUSICBRAINZ_ARTISTID 101 * - MUSICBRAINZ_ALBUMARTISTID 102 * - ACOUSTID_ID 103 * - ACOUSTID_FINGERPRINT 104 * - MUSICIP_PUID 105 * 106 */ 107 108 class TAGLIB_EXPORT PropertyMap: public SimplePropertyMap 109 { 110 public: 111 112 typedef SimplePropertyMap::Iterator Iterator; 113 typedef SimplePropertyMap::ConstIterator ConstIterator; 114 115 PropertyMap(); 116 117 PropertyMap(const PropertyMap &m); 118 119 /*! 120 * Creates a PropertyMap initialized from a SimplePropertyMap. Copies all 121 * entries from \a m that have valid keys. 122 * Invalid keys will be appended to the unsupportedData() list. 123 */ 124 PropertyMap(const SimplePropertyMap &m); 125 126 virtual ~PropertyMap(); 127 128 /*! 129 * Inserts \a values under \a key in the map. If \a key already exists, 130 * then \a values will be appended to the existing StringList. 131 * The returned value indicates success, i.e. whether \a key is a 132 * valid key. 133 */ 134 bool insert(const String &key, const StringList &values); 135 136 /*! 137 * Replaces any existing values for \a key with the given \a values, 138 * and simply insert them if \a key did not exist before. 139 * The returned value indicates success, i.e. whether \a key is a 140 * valid key. 141 */ 142 bool replace(const String &key, const StringList &values); 143 144 /*! 145 * Find the first occurrence of \a key. 146 */ 147 Iterator find(const String &key); 148 149 /*! 150 * Find the first occurrence of \a key. 151 */ 152 ConstIterator find(const String &key) const; 153 154 /*! 155 * Returns true if the map contains values for \a key. 156 */ 157 bool contains(const String &key) const; 158 159 /*! 160 * Returns true if this map contains all keys of \a other 161 * and the values coincide for that keys. Does not take 162 * the unsupportedData list into account. 163 */ 164 bool contains(const PropertyMap &other) const; 165 166 /*! 167 * Erase the \a key and its values from the map. 168 */ 169 PropertyMap &erase(const String &key); 170 171 /*! 172 * Erases from this map all keys that appear in \a other. 173 */ 174 PropertyMap &erase(const PropertyMap &other); 175 176 /*! 177 * Merge the contents of \a other into this PropertyMap. 178 * If a key is contained in both maps, the values of the second 179 * are appended to that of the first. 180 * The unsupportedData() lists are concatenated as well. 181 */ 182 PropertyMap &merge(const PropertyMap &other); 183 184 /*! 185 * Returns a reference to the value associated with \a key. 186 * 187 * \note: If \a key is not contained in the map, an empty 188 * StringList is returned without error. 189 */ 190 const StringList &operator[](const String &key) const; 191 192 /*! 193 * Returns a reference to the value associated with \a key. 194 * 195 * \note: If \a key is not contained in the map, an empty 196 * StringList is returned. You can also directly add entries 197 * by using this function as an lvalue. 198 */ 199 StringList &operator[](const String &key); 200 201 /*! 202 * Returns true if and only if \other has the same contents as this map. 203 */ 204 bool operator==(const PropertyMap &other) const; 205 206 /*! 207 * Returns false if and only \other has the same contents as this map. 208 */ 209 bool operator!=(const PropertyMap &other) const; 210 211 /*! 212 * If a PropertyMap is read from a File object using File::properties(), 213 * the StringList returned from this function will represent metadata 214 * that could not be parsed into the PropertyMap representation. This could 215 * be e.g. binary data, unknown ID3 frames, etc. 216 * You can remove items from the returned list, which tells TagLib to remove 217 * those unsupported elements if you call File::setProperties() with the 218 * same PropertyMap as argument. 219 */ 220 StringList &unsupportedData(); 221 const StringList &unsupportedData() const; 222 223 /*! 224 * Removes all entries which have an empty value list. 225 */ 226 void removeEmpty(); 227 228 String toString() const; 229 230 private: 231 232 233 StringList unsupported; 234 }; 235 236 } 237 #endif /* TAGLIB_PROPERTYMAP_H_ */ 238