1 /*************************************************************************** 2 copyright : (C) 2004 by Allan Sandfeld Jensen 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_APETAG_H 27 #define TAGLIB_APETAG_H 28 29 #include "tag.h" 30 #include "tbytevector.h" 31 #include "tmap.h" 32 #include "tstring.h" 33 #include "taglib_export.h" 34 35 #include "apeitem.h" 36 37 namespace TagLib { 38 39 class File; 40 41 //! An implementation of the APE tagging format 42 43 namespace APE { 44 45 class Footer; 46 47 /*! 48 * A mapping between a list of item names, or keys, and the associated item. 49 * 50 * \see APE::Tag::itemListMap() 51 */ 52 typedef Map<const String, Item> ItemListMap; 53 54 55 //! An APE tag implementation 56 57 class TAGLIB_EXPORT Tag : public TagLib::Tag 58 { 59 public: 60 /*! 61 * Create an APE tag with default values. 62 */ 63 Tag(); 64 65 /*! 66 * Create an APE tag and parse the data in \a file with APE footer at 67 * \a tagOffset. 68 */ 69 Tag(TagLib::File *file, long footerLocation); 70 71 /*! 72 * Destroys this Tag instance. 73 */ 74 virtual ~Tag(); 75 76 /*! 77 * Renders the in memory values to a ByteVector suitable for writing to 78 * the file. 79 */ 80 ByteVector render() const; 81 82 /*! 83 * Returns the string "APETAGEX" suitable for usage in locating the tag in a 84 * file. 85 */ 86 static ByteVector fileIdentifier(); 87 88 // Reimplementations. 89 90 virtual String title() const; 91 virtual String artist() const; 92 virtual String album() const; 93 virtual String comment() const; 94 virtual String genre() const; 95 virtual unsigned int year() const; 96 virtual unsigned int track() const; 97 98 virtual void setTitle(const String &s); 99 virtual void setArtist(const String &s); 100 virtual void setAlbum(const String &s); 101 virtual void setComment(const String &s); 102 virtual void setGenre(const String &s); 103 virtual void setYear(unsigned int i); 104 virtual void setTrack(unsigned int i); 105 106 /*! 107 * Implements the unified tag dictionary interface -- export function. 108 * APE tags are perfectly compatible with the dictionary interface because they 109 * support both arbitrary tag names and multiple values. Currently only 110 * APE items of type *Text* are handled by the dictionary interface; all *Binary* 111 * and *Locator* items will be put into the unsupportedData list and can be 112 * deleted on request using removeUnsupportedProperties(). The same happens 113 * to Text items if their key is invalid for PropertyMap (which should actually 114 * never happen). 115 * 116 * The only conversion done by this export function is to rename the APE tags 117 * TRACK to TRACKNUMBER, YEAR to DATE, and ALBUM ARTIST to ALBUMARTIST, respectively, 118 * in order to be compliant with the names used in other formats. 119 */ 120 PropertyMap properties() const; 121 122 void removeUnsupportedProperties(const StringList &properties); 123 124 /*! 125 * Implements the unified tag dictionary interface -- import function. The same 126 * comments as for the export function apply; additionally note that the APE tag 127 * specification requires keys to have between 2 and 16 printable ASCII characters 128 * with the exception of the fixed strings "ID3", "TAG", "OGGS", and "MP+". 129 */ 130 PropertyMap setProperties(const PropertyMap &); 131 132 /*! 133 * Check if the given String is a valid APE tag key. 134 */ 135 static bool checkKey(const String&); 136 137 /*! 138 * Returns a pointer to the tag's footer. 139 */ 140 Footer *footer() const; 141 142 /*! 143 * Returns a reference to the item list map. This is an ItemListMap of 144 * all of the items in the tag. 145 * 146 * This is the most powerful structure for accessing the items of the tag. 147 * 148 * APE tags are case-insensitive, all keys in this map have been converted 149 * to upper case. 150 * 151 * \warning You should not modify this data structure directly, instead 152 * use setItem() and removeItem(). 153 */ 154 const ItemListMap &itemListMap() const; 155 156 /*! 157 * Removes the \a key item from the tag 158 */ 159 void removeItem(const String &key); 160 161 /*! 162 * Adds to the text item specified by \a key the data \a value. If \a replace 163 * is true, then all of the other values on the same key will be removed 164 * first. If a binary item exists for \a key it will be removed first. 165 */ 166 void addValue(const String &key, const String &value, bool replace = true); 167 168 /*! 169 * Set the binary data for the key specified by \a item to \a value 170 * This will convert the item to type \a Binary if it isn't already and 171 * all of the other values on the same key will be removed. 172 */ 173 void setData(const String &key, const ByteVector &value); 174 175 /*! 176 * Sets the \a key item to the value of \a item. If an item with the \a key is already 177 * present, it will be replaced. 178 */ 179 void setItem(const String &key, const Item &item); 180 181 /*! 182 * Returns true if the tag does not contain any data. 183 */ 184 bool isEmpty() const; 185 186 protected: 187 188 /*! 189 * Reads from the file specified in the constructor. 190 */ 191 void read(); 192 193 /*! 194 * Parses the body of the tag in \a data. 195 */ 196 void parse(const ByteVector &data); 197 198 private: 199 Tag(const Tag &); 200 Tag &operator=(const Tag &); 201 202 class TagPrivate; 203 TagPrivate *d; 204 }; 205 } 206 } 207 208 #endif 209