1/***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.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_TAG_H
27#define TAGLIB_TAG_H
28
29#include "taglib_export.h"
30#include "tstring.h"
31
32namespace TagLib {
33
34 //! A simple, generic interface to common audio meta data fields
35
36 /*!
37 * This is an attempt to abstract away the difference in the meta data formats
38 * of various audio codecs and tagging schemes. As such it is generally a
39 * subset of what is available in the specific formats but should be suitable
40 * for most applications. This is meant to compliment the generic APIs found
41 * in TagLib::AudioProperties, TagLib::File and TagLib::FileRef.
42 */
43
44 class PropertyMap;
45
46 class TAGLIB_EXPORT Tag
47 {
48 public:
49
50 /*!
51 * Detroys this Tag instance.
52 */
53 virtual ~Tag();
54
55 /*!
56 * Exports the tags of the file as dictionary mapping (human readable) tag
57 * names (Strings) to StringLists of tag values.
58 * The default implementation in this class considers only the usual built-in
59 * tags (artist, album, ...) and only one value per key.
60 */
61 PropertyMap properties() const;
62
63 /*!
64 * Removes unsupported properties, or a subset of them, from the tag.
65 * The parameter \a properties must contain only entries from
66 * properties().unsupportedData().
67 * BIC: Will become virtual in future releases. Currently the non-virtual
68 * standard implementation of TagLib::Tag does nothing, since there are
69 * no unsupported elements.
70 */
71 void removeUnsupportedProperties(const StringList& properties);
72
73 /*!
74 * Sets the tags of this File to those specified in \a properties. This default
75 * implementation sets only the tags for which setter methods exist in this class
76 * (artist, album, ...), and only one value per key; the rest will be contained
77 * in the returned PropertyMap.
78 */
79 PropertyMap setProperties(const PropertyMap &properties);
80
81 /*!
82 * Returns the track name; if no track name is present in the tag
83 * String::null will be returned.
84 */
85 virtual String title() const = 0;
86
87 /*!
88 * Returns the artist name; if no artist name is present in the tag
89 * String::null will be returned.
90 */
91 virtual String artist() const = 0;
92
93 /*!
94 * Returns the album name; if no album name is present in the tag
95 * String::null will be returned.
96 */
97 virtual String album() const = 0;
98
99 /*!
100 * Returns the track comment; if no comment is present in the tag
101 * String::null will be returned.
102 */
103 virtual String comment() const = 0;
104
105 /*!
106 * Returns the genre name; if no genre is present in the tag String::null
107 * will be returned.
108 */
109 virtual String genre() const = 0;
110
111 /*!
112 * Returns the year; if there is no year set, this will return 0.
113 */
114 virtual uint year() const = 0;
115
116 /*!
117 * Returns the track number; if there is no track number set, this will
118 * return 0.
119 */
120 virtual uint track() const = 0;
121
122 /*!
123 * Sets the title to \a s. If \a s is String::null then this value will be
124 * cleared.
125 */
126 virtual void setTitle(const String &s) = 0;
127
128 /*!
129 * Sets the artist to \a s. If \a s is String::null then this value will be
130 * cleared.
131 */
132 virtual void setArtist(const String &s) = 0;
133
134 /*!
135 * Sets the album to \a s. If \a s is String::null then this value will be
136 * cleared.
137 */
138 virtual void setAlbum(const String &s) = 0;
139
140 /*!
141 * Sets the comment to \a s. If \a s is String::null then this value will be
142 * cleared.
143 */
144 virtual void setComment(const String &s) = 0;
145
146 /*!
147 * Sets the genre to \a s. If \a s is String::null then this value will be
148 * cleared. For tag formats that use a fixed set of genres, the appropriate
149 * value will be selected based on a string comparison. A list of available
150 * genres for those formats should be available in that type's
151 * implementation.
152 */
153 virtual void setGenre(const String &s) = 0;
154
155 /*!
156 * Sets the year to \a i. If \a s is 0 then this value will be cleared.
157 */
158 virtual void setYear(uint i) = 0;
159
160 /*!
161 * Sets the track to \a i. If \a s is 0 then this value will be cleared.
162 */
163 virtual void setTrack(uint i) = 0;
164
165 /*!
166 * Returns true if the tag does not contain any data. This should be
167 * reimplemented in subclasses that provide more than the basic tagging
168 * abilities in this class.
169 */
170 virtual bool isEmpty() const;
171
172 /*!
173 * Copies the generic data from one tag to another.
174 *
175 * \note This will no affect any of the lower level details of the tag. For
176 * instance if any of the tag type specific data (maybe a URL for a band) is
177 * set, this will not modify or copy that. This just copies using the API
178 * in this class.
179 *
180 * If \a overwrite is true then the values will be unconditionally copied.
181 * If false only empty values will be overwritten.
182 */
183 static void duplicate(const Tag *source, Tag *target, bool overwrite = true);
184
185 protected:
186 /*!
187 * Construct a Tag. This is protected since tags should only be instantiated
188 * through subclasses.
189 */
190 Tag();
191
192 private:
193 Tag(const Tag &);
194 Tag &operator=(const Tag &);
195
196 class TagPrivate;
197 TagPrivate *d;
198 };
199}
200
201#endif
202