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_APETAG_H
27#define TAGLIB_APETAG_H
28
29#include "tag.h"
30#include "tbytevector.h"
31#include "tmap.h"
32#include "tstring.h"
33#include "taglib_export.h"
34
35#include "apeitem.h"
36
37namespace TagLib {
38
39 class File;
40
41 //! An implementation of the APE tagging format
42
43 namespace APE {
44
45 class Footer;
46
47 /*!
48 * A mapping between a list of item names, or keys, and the associated item.
49 *
50 * \see APE::Tag::itemListMap()
51 */
52 typedef Map<const String, Item> ItemListMap;
53
54
55 //! An APE tag implementation
56
57 class TAGLIB_EXPORT Tag : public TagLib::Tag
58 {
59 public:
60 /*!
61 * Create an APE tag with default values.
62 */
63 Tag();
64
65 /*!
66 * Create an APE tag and parse the data in \a file with APE footer at
67 * \a tagOffset.
68 */
69 Tag(TagLib::File *file, long footerLocation);
70
71 /*!
72 * Destroys this Tag instance.
73 */
74 virtual ~Tag();
75
76 /*!
77 * Renders the in memory values to a ByteVector suitable for writing to
78 * the file.
79 */
80 ByteVector render() const;
81
82 /*!
83 * Returns the string "APETAGEX" suitable for usage in locating the tag in a
84 * file.
85 */
86 static ByteVector fileIdentifier();
87
88 // Reimplementations.
89
90 virtual String title() const;
91 virtual String artist() const;
92 virtual String album() const;
93 virtual String comment() const;
94 virtual String genre() const;
95 virtual unsigned int year() const;
96 virtual unsigned int track() const;
97
98 virtual void setTitle(const String &s);
99 virtual void setArtist(const String &s);
100 virtual void setAlbum(const String &s);
101 virtual void setComment(const String &s);
102 virtual void setGenre(const String &s);
103 virtual void setYear(unsigned int i);
104 virtual void setTrack(unsigned int i);
105
106 /*!
107 * Implements the unified tag dictionary interface -- export function.
108 * APE tags are perfectly compatible with the dictionary interface because they
109 * support both arbitrary tag names and multiple values. Currently only
110 * APE items of type *Text* are handled by the dictionary interface; all *Binary*
111 * and *Locator* items will be put into the unsupportedData list and can be
112 * deleted on request using removeUnsupportedProperties(). The same happens
113 * to Text items if their key is invalid for PropertyMap (which should actually
114 * never happen).
115 *
116 * The only conversion done by this export function is to rename the APE tags
117 * TRACK to TRACKNUMBER, YEAR to DATE, and ALBUM ARTIST to ALBUMARTIST, respectively,
118 * in order to be compliant with the names used in other formats.
119 */
120 PropertyMap properties() const;
121
122 void removeUnsupportedProperties(const StringList &properties);
123
124 /*!
125 * Implements the unified tag dictionary interface -- import function. The same
126 * comments as for the export function apply; additionally note that the APE tag
127 * specification requires keys to have between 2 and 16 printable ASCII characters
128 * with the exception of the fixed strings "ID3", "TAG", "OGGS", and "MP+".
129 */
130 PropertyMap setProperties(const PropertyMap &);
131
132 /*!
133 * Check if the given String is a valid APE tag key.
134 */
135 static bool checkKey(const String&);
136
137 /*!
138 * Returns a pointer to the tag's footer.
139 */
140 Footer *footer() const;
141
142 /*!
143 * Returns a reference to the item list map. This is an ItemListMap of
144 * all of the items in the tag.
145 *
146 * This is the most powerful structure for accessing the items of the tag.
147 *
148 * APE tags are case-insensitive, all keys in this map have been converted
149 * to upper case.
150 *
151 * \warning You should not modify this data structure directly, instead
152 * use setItem() and removeItem().
153 */
154 const ItemListMap &itemListMap() const;
155
156 /*!
157 * Removes the \a key item from the tag
158 */
159 void removeItem(const String &key);
160
161 /*!
162 * Adds to the text item specified by \a key the data \a value. If \a replace
163 * is true, then all of the other values on the same key will be removed
164 * first. If a binary item exists for \a key it will be removed first.
165 */
166 void addValue(const String &key, const String &value, bool replace = true);
167
168 /*!
169 * Set the binary data for the key specified by \a item to \a value
170 * This will convert the item to type \a Binary if it isn't already and
171 * all of the other values on the same key will be removed.
172 */
173 void setData(const String &key, const ByteVector &value);
174
175 /*!
176 * Sets the \a key item to the value of \a item. If an item with the \a key is already
177 * present, it will be replaced.
178 */
179 void setItem(const String &key, const Item &item);
180
181 /*!
182 * Returns true if the tag does not contain any data.
183 */
184 bool isEmpty() const;
185
186 protected:
187
188 /*!
189 * Reads from the file specified in the constructor.
190 */
191 void read();
192
193 /*!
194 * Parses the body of the tag in \a data.
195 */
196 void parse(const ByteVector &data);
197
198 private:
199 Tag(const Tag &);
200 Tag &operator=(const Tag &);
201
202 class TagPrivate;
203 TagPrivate *d;
204 };
205 }
206}
207
208#endif
209