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_APEITEM_H 27 #define TAGLIB_APEITEM_H 28 29 #include "tbytevector.h" 30 #include "tstring.h" 31 #include "tstringlist.h" 32 33 namespace TagLib { 34 35 namespace APE { 36 37 //! An implementation of APE-items 38 39 /*! 40 * This class provides the features of items in the APEv2 standard. 41 */ 42 class TAGLIB_EXPORT Item 43 { 44 public: 45 /*! 46 * Enum of types an Item can have. The value of 3 is reserved. 47 */ 48 enum ItemTypes { 49 //! Item contains text information coded in UTF-8 50 Text = 0, 51 //! Item contains binary information 52 Binary = 1, 53 //! Item is a locator of external stored information 54 Locator = 2 55 }; 56 /*! 57 * Constructs an empty item. 58 */ 59 Item(); 60 61 /*! 62 * Constructs a text item with \a key and \a value. 63 */ 64 // BIC: Remove this, StringList has a constructor from a single string 65 Item(const String &key, const String &value); 66 67 /*! 68 * Constructs a text item with \a key and \a values. 69 */ 70 Item(const String &key, const StringList &values); 71 72 /*! 73 * Constructs an item with \a key and \a value. 74 * If \a binary is true a Binary item will be created, otherwise \a value will be interpreted as text 75 */ 76 Item(const String &key, const ByteVector &value, bool binary); 77 78 /*! 79 * Construct an item as a copy of \a item. 80 */ 81 Item(const Item &item); 82 83 /*! 84 * Destroys the item. 85 */ 86 virtual ~Item(); 87 88 /*! 89 * Copies the contents of \a item into this item. 90 */ 91 Item &operator=(const Item &item); 92 93 /*! 94 * Exchanges the content of this item by the content of \a item. 95 */ 96 void swap(Item &item); 97 98 /*! 99 * Returns the key. 100 */ 101 String key() const; 102 103 /*! 104 * Returns the binary value. 105 * If the item type is not \a Binary, always returns an empty ByteVector. 106 */ 107 ByteVector binaryData() const; 108 109 /*! 110 * Set the binary value to \a value 111 * The item's type will also be set to \a Binary 112 */ 113 void setBinaryData(const ByteVector &value); 114 115 #ifndef DO_NOT_DOCUMENT 116 /* Remove in next binary incompatible release */ 117 ByteVector value() const; 118 #endif 119 120 /*! 121 * Sets the key for the item to \a key. 122 */ 123 void setKey(const String &key); 124 125 /*! 126 * Sets the text value of the item to \a value and clears any previous contents. 127 * 128 * \see toString() 129 */ 130 void setValue(const String &value); 131 132 /*! 133 * Sets the text value of the item to the list of values in \a value and clears 134 * any previous contents. 135 * 136 * \see toStringList() 137 */ 138 void setValues(const StringList &values); 139 140 /*! 141 * Appends \a value to create (or extend) the current list of text values. 142 * 143 * \see toString() 144 */ 145 void appendValue(const String &value); 146 147 /*! 148 * Appends \a values to extend the current list of text values. 149 * 150 * \see toStringList() 151 */ 152 void appendValues(const StringList &values); 153 154 /*! 155 * Returns the size of the full item. 156 */ 157 int size() const; 158 159 /*! 160 * Returns the value as a single string. In case of multiple strings, 161 * the first is returned. If the data type is not \a Text, always returns 162 * an empty String. 163 */ 164 String toString() const; 165 166 #ifndef DO_NOT_DOCUMENT 167 /* Remove in next binary incompatible release */ 168 StringList toStringList() const; 169 #endif 170 171 /*! 172 * Returns the list of text values. If the data type is not \a Text, always 173 * returns an empty StringList. 174 */ 175 StringList values() const; 176 177 /*! 178 * Render the item to a ByteVector. 179 */ 180 ByteVector render() const; 181 182 /*! 183 * Parse the item from the ByteVector \a data. 184 */ 185 void parse(const ByteVector& data); 186 187 /*! 188 * Set the item to read-only. 189 */ 190 void setReadOnly(bool readOnly); 191 192 /*! 193 * Return true if the item is read-only. 194 */ 195 bool isReadOnly() const; 196 197 /*! 198 * Sets the type of the item to \a type. 199 * 200 * \see ItemTypes 201 */ 202 void setType(ItemTypes type); 203 204 /*! 205 * Returns the type of the item. 206 */ 207 ItemTypes type() const; 208 209 /*! 210 * Returns if the item has any real content. 211 */ 212 bool isEmpty() const; 213 214 private: 215 class ItemPrivate; 216 ItemPrivate *d; 217 }; 218 } 219 220 } 221 222 #endif 223 224 225