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_ID3V1TAG_H 27 #define TAGLIB_ID3V1TAG_H 28 29 #include "tag.h" 30 #include "tbytevector.h" 31 #include "taglib_export.h" 32 33 namespace TagLib { 34 35 class File; 36 37 //! An ID3v1 implementation 38 39 namespace ID3v1 { 40 41 //! A abstraction for the string to data encoding in ID3v1 tags. 42 43 /*! 44 * ID3v1 should in theory always contain ISO-8859-1 (Latin1) data. In 45 * practice it does not. TagLib by default only supports ISO-8859-1 data 46 * in ID3v1 tags. 47 * 48 * However by subclassing this class and reimplementing parse() and render() 49 * and setting your reimplementation as the default with 50 * ID3v1::Tag::setStringHandler() you can define how you would like these 51 * transformations to be done. 52 * 53 * \warning It is advisable <b>not</b> to write non-ISO-8859-1 data to ID3v1 54 * tags. Please consider disabling the writing of ID3v1 tags in the case 55 * that the data is not ISO-8859-1. 56 * 57 * \see ID3v1::Tag::setStringHandler() 58 */ 59 60 class TAGLIB_EXPORT StringHandler 61 { 62 TAGLIB_IGNORE_MISSING_DESTRUCTOR 63 public: 64 // BIC: Add virtual destructor. 65 StringHandler(); 66 67 /*! 68 * Decode a string from \a data. The default implementation assumes that 69 * \a data is an ISO-8859-1 (Latin1) character array. 70 */ 71 virtual String parse(const ByteVector &data) const; 72 73 /*! 74 * Encode a ByteVector with the data from \a s. The default implementation 75 * assumes that \a s is an ISO-8859-1 (Latin1) string. If the string is 76 * does not conform to ISO-8859-1, no value is written. 77 * 78 * \warning It is recommended that you <b>not</b> override this method, but 79 * instead do not write an ID3v1 tag in the case that the data is not 80 * ISO-8859-1. 81 */ 82 virtual ByteVector render(const String &s) const; 83 }; 84 85 //! The main class in the ID3v1 implementation 86 87 /*! 88 * This is an implementation of the ID3v1 format. ID3v1 is both the simplest 89 * and most common of tag formats but is rather limited. Because of its 90 * pervasiveness and the way that applications have been written around the 91 * fields that it provides, the generic TagLib::Tag API is a mirror of what is 92 * provided by ID3v1. 93 * 94 * ID3v1 tags should generally only contain Latin1 information. However because 95 * many applications do not follow this rule there is now support for overriding 96 * the ID3v1 string handling using the ID3v1::StringHandler class. Please see 97 * the documentation for that class for more information. 98 * 99 * \see StringHandler 100 * 101 * \note Most fields are truncated to a maximum of 28-30 bytes. The 102 * truncation happens automatically when the tag is rendered. 103 */ 104 105 class TAGLIB_EXPORT Tag : public TagLib::Tag 106 { 107 public: 108 /*! 109 * Create an ID3v1 tag with default values. 110 */ 111 Tag(); 112 113 /*! 114 * Create an ID3v1 tag and parse the data in \a file starting at 115 * \a tagOffset. 116 */ 117 Tag(File *file, long tagOffset); 118 119 /*! 120 * Destroys this Tag instance. 121 */ 122 virtual ~Tag(); 123 124 /*! 125 * Renders the in memory values to a ByteVector suitable for writing to 126 * the file. 127 */ 128 ByteVector render() const; 129 130 /*! 131 * Returns the string "TAG" suitable for usage in locating the tag in a 132 * file. 133 */ 134 static ByteVector fileIdentifier(); 135 136 // Reimplementations. 137 138 virtual String title() const; 139 virtual String artist() const; 140 virtual String album() const; 141 virtual String comment() const; 142 virtual String genre() const; 143 virtual unsigned int year() const; 144 virtual unsigned int track() const; 145 146 virtual void setTitle(const String &s); 147 virtual void setArtist(const String &s); 148 virtual void setAlbum(const String &s); 149 virtual void setComment(const String &s); 150 virtual void setGenre(const String &s); 151 virtual void setYear(unsigned int i); 152 virtual void setTrack(unsigned int i); 153 154 /*! 155 * Returns the genre in number. 156 * 157 * \note Normally 255 indicates that this tag contains no genre. 158 */ 159 unsigned int genreNumber() const; 160 161 /*! 162 * Sets the genre in number to \a i. 163 * 164 * \note Valid value is from 0 up to 255. Normally 255 indicates that 165 * this tag contains no genre. 166 */ 167 void setGenreNumber(unsigned int i); 168 169 /*! 170 * Sets the string handler that decides how the ID3v1 data will be 171 * converted to and from binary data. 172 * If the parameter \a handler is null, the previous handler is 173 * released and default ISO-8859-1 handler is restored. 174 * 175 * \note The caller is responsible for deleting the previous handler 176 * as needed after it is released. 177 * 178 * \see StringHandler 179 */ 180 static void setStringHandler(const StringHandler *handler); 181 182 protected: 183 /*! 184 * Reads from the file specified in the constructor. 185 */ 186 void read(); 187 /*! 188 * Pareses the body of the tag in \a data. 189 */ 190 void parse(const ByteVector &data); 191 192 private: 193 Tag(const Tag &); 194 Tag &operator=(const Tag &); 195 196 class TagPrivate; 197 TagPrivate *d; 198 }; 199 } 200 } 201 202 #endif 203