1 /***************************************************************************
2 copyright : (C) 2004 by Allan Sandfeld Jensen
3 email : kde@carewolf.org
4 ***************************************************************************/
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. *
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. *
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
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 ***************************************************************************/
26 #ifndef TAGLIB_APEITEM_H
27 #define TAGLIB_APEITEM_H
29 #include "tbytevector.h"
31 #include "tstringlist.h"
37 //! An implementation of APE-items
40 * This class provides the features of items in the APEv2 standard.
42 class TAGLIB_EXPORT Item
46 * Enum of types an Item can have. The value of 3 is reserved.
49 //! Item contains text information coded in UTF-8
51 //! Item contains binary information
53 //! Item is a locator of external stored information
57 * Constructs an empty item.
62 * Constructs an item with \a key and \a value.
64 // BIC: Remove this, StringList has a constructor from a single string
65 Item(const String &key, const String &value);
68 * Constructs an item with \a key and \a values.
70 Item(const String &key, const StringList &values);
73 * Construct an item as a copy of \a item.
75 Item(const Item &item);
83 * Copies the contents of \a item into this item.
85 Item &operator=(const Item &item);
93 * Returns the binary value.
95 * \deprecated This will be removed in the next binary incompatible version
96 * as it is not kept in sync with the things that are set using setValue()
99 ByteVector value() const;
102 * Sets the key for the item to \a key.
104 void setKey(const String &key);
107 * Sets the value of the item to \a value and clears any previous contents.
111 void setValue(const String &value);
114 * Sets the value of the item to the list of values in \a value and clears
115 * any previous contents.
117 * \see toStringList()
119 void setValues(const StringList &values);
122 * Appends \a value to create (or extend) the current list of values.
126 void appendValue(const String &value);
129 * Appends \a values to extend the current list of values.
131 * \see toStringList()
133 void appendValues(const StringList &values);
136 * Returns the size of the full item.
141 * Returns the value as a single string. In case of multiple strings,
142 * the first is returned.
144 String toString() const;
150 StringList toStringList() const;
153 * Returns the list of values.
155 StringList values() const;
158 * Render the item to a ByteVector.
160 ByteVector render() const;
163 * Parse the item from the ByteVector \a data.
165 void parse(const ByteVector& data);
168 * Set the item to read-only.
170 void setReadOnly(bool readOnly);
173 * Return true if the item is read-only.
175 bool isReadOnly() const;
178 * Sets the type of the item to \a type.
182 void setType(ItemTypes type);
185 * Returns the type of the item.
187 ItemTypes type() const;
190 * Returns if the item has any real content.
192 bool isEmpty() const;