1 /*************************************************************************** 2 copyright : (C) 2012 by Tsuda Kageyu 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_INFOTAG_H 27 #define TAGLIB_INFOTAG_H 28 29 #include "tag.h" 30 #include "tmap.h" 31 #include "tstring.h" 32 #include "tstringlist.h" 33 #include "tbytevector.h" 34 #include "taglib_export.h" 35 36 namespace TagLib { 37 38 class File; 39 40 //! A RIFF INFO tag implementation. 41 namespace RIFF { 42 namespace Info { 43 44 typedef Map<ByteVector, String> FieldListMap; 45 46 //! A abstraction for the string to data encoding in Info tags. 47 48 /*! 49 * RIFF INFO tag has no clear definitions about character encodings. 50 * In practice, local encoding of each system is largely used and UTF-8 is 51 * popular too. 52 * 53 * Here is an option to read and write tags in your preferred encoding 54 * by subclassing this class, reimplementing parse() and render() and setting 55 * your reimplementation as the default with Info::Tag::setStringHandler(). 56 * 57 * \see ID3v1::Tag::setStringHandler() 58 */ 59 60 class TAGLIB_EXPORT StringHandler 61 { 62 public: 63 StringHandler(); 64 ~StringHandler(); 65 66 /*! 67 * Decode a string from \a data. The default implementation assumes that 68 * \a data is an UTF-8 character array. 69 */ 70 virtual String parse(const ByteVector &data) const; 71 72 /*! 73 * Encode a ByteVector with the data from \a s. The default implementation 74 * assumes that \a s is an UTF-8 string. 75 */ 76 virtual ByteVector render(const String &s) const; 77 }; 78 79 //! The main class in the ID3v2 implementation 80 81 /*! 82 * This is the main class in the INFO tag implementation. RIFF INFO tag is a 83 * metadata format found in WAV audio and AVI video files. Though it is a part 84 * of Microsoft/IBM's RIFF specification, the author could not find the official 85 * documents about it. So, this implementation is referring to unofficial documents 86 * online and some applications' behaviors especially Windows Explorer. 87 */ 88 class TAGLIB_EXPORT Tag : public TagLib::Tag 89 { 90 public: 91 /*! 92 * Constructs an empty INFO tag. 93 */ 94 Tag(); 95 96 /*! 97 * Constructs an INFO tag read from \a data which is contents of "LIST" chunk. 98 */ 99 Tag(const ByteVector &data); 100 101 virtual ~Tag(); 102 103 // Reimplementations 104 105 virtual String title() const; 106 virtual String artist() const; 107 virtual String album() const; 108 virtual String comment() const; 109 virtual String genre() const; 110 virtual unsigned int year() const; 111 virtual unsigned int track() const; 112 113 virtual void setTitle(const String &s); 114 virtual void setArtist(const String &s); 115 virtual void setAlbum(const String &s); 116 virtual void setComment(const String &s); 117 virtual void setGenre(const String &s); 118 virtual void setYear(unsigned int i); 119 virtual void setTrack(unsigned int i); 120 121 virtual bool isEmpty() const; 122 123 /*! 124 * Returns a copy of the internal fields of the tag. The returned map directly 125 * reflects the contents of the "INFO" chunk. 126 * 127 * \note Modifying this map does not affect the tag's internal data. 128 * Use setFieldText() and removeField() instead. 129 * 130 * \see setFieldText() 131 * \see removeField() 132 */ 133 FieldListMap fieldListMap() const; 134 135 /* 136 * Gets the value of the field with the ID \a id. 137 */ 138 String fieldText(const ByteVector &id) const; 139 140 /* 141 * Sets the value of the field with the ID \a id to \a s. 142 * If the field does not exist, it is created. 143 * If \s is empty, the field is removed. 144 * 145 * \note fieldId must be four-byte long pure ASCII string. This function 146 * performs nothing if fieldId is invalid. 147 */ 148 void setFieldText(const ByteVector &id, const String &s); 149 150 /* 151 * Removes the field with the ID \a id. 152 */ 153 void removeField(const ByteVector &id); 154 155 /*! 156 * Render the tag back to binary data, suitable to be written to disk. 157 * 158 * \note Returns empty ByteVector is the tag contains no fields. 159 */ 160 ByteVector render() const; 161 162 /*! 163 * Sets the string handler that decides how the text data will be 164 * converted to and from binary data. 165 * If the parameter \a handler is null, the previous handler is 166 * released and default UTF-8 handler is restored. 167 * 168 * \note The caller is responsible for deleting the previous handler 169 * as needed after it is released. 170 * 171 * \see StringHandler 172 */ 173 static void setStringHandler(const StringHandler *handler); 174 175 protected: 176 /*! 177 * Pareses the body of the tag in \a data. 178 */ 179 void parse(const ByteVector &data); 180 181 182 private: 183 Tag(const Tag &); 184 Tag &operator=(const Tag &); 185 186 class TagPrivate; 187 TagPrivate *d; 188 }; 189 }} 190 } 191 192 #endif 193