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 | |
32 | namespace 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 () 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 (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 | |