1/***************************************************************************
2 copyright : (C) 2004 by Allan Sandfeld Jensen
3 email : kde@carewolf.org
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
33namespace 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