1 /***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.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_TEXTIDENTIFICATIONFRAME_H
27 #define TAGLIB_TEXTIDENTIFICATIONFRAME_H
29 #include "tstringlist.h"
30 #include "taglib_export.h"
32 #include "id3v2frame.h"
40 //! An ID3v2 text identification frame implementation
43 * This is an implementation of the most common type of ID3v2 frame -- text
44 * identification frames. There are a number of variations on this. Those
45 * enumerated in the ID3v2.4 standard are:
48 * <li><b>TALB</b> Album/Movie/Show title</li>
49 * <li><b>TBPM</b> BPM (beats per minute)</li>
50 * <li><b>TCOM</b> Composer</li>
51 * <li><b>TCON</b> Content type</li>
52 * <li><b>TCOP</b> Copyright message</li>
53 * <li><b>TDEN</b> Encoding time</li>
54 * <li><b>TDLY</b> Playlist delay</li>
55 * <li><b>TDOR</b> Original release time</li>
56 * <li><b>TDRC</b> Recording time</li>
57 * <li><b>TDRL</b> Release time</li>
58 * <li><b>TDTG</b> Tagging time</li>
59 * <li><b>TENC</b> Encoded by</li>
60 * <li><b>TEXT</b> Lyricist/Text writer</li>
61 * <li><b>TFLT</b> File type</li>
62 * <li><b>TIPL</b> Involved people list</li>
63 * <li><b>TIT1</b> Content group description</li>
64 * <li><b>TIT2</b> Title/songname/content description</li>
65 * <li><b>TIT3</b> Subtitle/Description refinement</li>
66 * <li><b>TKEY</b> Initial key</li>
67 * <li><b>TLAN</b> Language(s)</li>
68 * <li><b>TLEN</b> Length</li>
69 * <li><b>TMCL</b> Musician credits list</li>
70 * <li><b>TMED</b> Media type</li>
71 * <li><b>TMOO</b> Mood</li>
72 * <li><b>TOAL</b> Original album/movie/show title</li>
73 * <li><b>TOFN</b> Original filename</li>
74 * <li><b>TOLY</b> Original lyricist(s)/text writer(s)</li>
75 * <li><b>TOPE</b> Original artist(s)/performer(s)</li>
76 * <li><b>TOWN</b> File owner/licensee</li>
77 * <li><b>TPE1</b> Lead performer(s)/Soloist(s)</li>
78 * <li><b>TPE2</b> Band/orchestra/accompaniment</li>
79 * <li><b>TPE3</b> Conductor/performer refinement</li>
80 * <li><b>TPE4</b> Interpreted, remixed, or otherwise modified by</li>
81 * <li><b>TPOS</b> Part of a set</li>
82 * <li><b>TPRO</b> Produced notice</li>
83 * <li><b>TPUB</b> Publisher</li>
84 * <li><b>TRCK</b> Track number/Position in set</li>
85 * <li><b>TRSN</b> Internet radio station name</li>
86 * <li><b>TRSO</b> Internet radio station owner</li>
87 * <li><b>TSOA</b> Album sort order</li>
88 * <li><b>TSOP</b> Performer sort order</li>
89 * <li><b>TSOT</b> Title sort order</li>
90 * <li><b>TSRC</b> ISRC (international standard recording code)</li>
91 * <li><b>TSSE</b> Software/Hardware and settings used for encoding</li>
92 * <li><b>TSST</b> Set subtitle</li>
95 * The ID3v2 Frames document gives a description of each of these formats
96 * and the expected order of strings in each. ID3v2::Header::frameID() can
97 * be used to determine the frame type.
99 * \note If non-Latin1 compatible strings are used with this class, even if
100 * the text encoding is set to Latin1, the frame will be written using UTF8
101 * (with the encoding flag appropriately set in the output).
104 class TAGLIB_EXPORT TextIdentificationFrame : public Frame
106 friend class FrameFactory;
110 * Construct an empty frame of type \a type. Uses \a encoding as the
111 * default text encoding.
113 * \note In this case you must specify the text encoding as it
114 * resolves the ambiguity between constructors.
116 * \note Please see the note in the class description regarding Latin1.
118 TextIdentificationFrame(const ByteVector &type, String::Type encoding);
121 * This is a dual purpose constructor. \a data can either be binary data
122 * that should be parsed or (at a minimum) the frame ID.
124 explicit TextIdentificationFrame(const ByteVector &data);
127 * Destroys this TextIdentificationFrame instance.
129 virtual ~TextIdentificationFrame();
132 * Text identification frames are a list of string fields.
134 * This function will accept either a StringList or a String (using the
135 * StringList constructor that accepts a single String).
137 * \note This will not change the text encoding of the frame even if the
138 * strings passed in are not of the same encoding. Please use
139 * setEncoding(s.type()) if you wish to change the encoding of the frame.
141 void setText(const StringList &l);
143 // Reimplementations.
145 virtual void setText(const String &s);
146 virtual String toString() const;
149 * Returns the text encoding that will be used in rendering this frame.
150 * This defaults to the type that was either specified in the constructor
151 * or read from the frame when parsed.
153 * \note Please see the note in the class description regarding Latin1.
155 * \see setTextEncoding()
158 String::Type textEncoding() const;
161 * Sets the text encoding to be used when rendering this frame to
164 * \note Please see the note in the class description regarding Latin1.
166 * \see textEncoding()
169 void setTextEncoding(String::Type encoding);
172 * Returns a list of the strings in this frame.
174 StringList fieldList() const;
177 // Reimplementations.
179 virtual void parseFields(const ByteVector &data);
180 virtual ByteVector renderFields() const;
183 * The constructor used by the FrameFactory.
185 TextIdentificationFrame(const ByteVector &data, Header *h);
188 TextIdentificationFrame(const TextIdentificationFrame &);
189 TextIdentificationFrame &operator=(const TextIdentificationFrame &);
191 class TextIdentificationFramePrivate;
192 TextIdentificationFramePrivate *d;
196 * This is a specialization of text identification frames that allows for
197 * user defined entries. Each entry has a description in addition to the
198 * normal list of fields that a text identification frame has.
200 * This description identifies the frame and must be unique.
203 //! An ID3v2 custom text identification frame implementationx
205 class TAGLIB_EXPORT UserTextIdentificationFrame : public TextIdentificationFrame
207 friend class FrameFactory;
211 * Constructs an empty user defined text identification frame. For this to be
212 * a useful frame both a description and text must be set.
214 explicit UserTextIdentificationFrame(String::Type encoding = String::Latin1);
217 * Creates a frame based on \a data.
219 explicit UserTextIdentificationFrame(const ByteVector &data);
221 virtual String toString() const;
224 * Returns the description for this frame.
226 String description() const;
229 * Sets the description of the frame to \a s. \a s must be unique. You can
230 * check for the presence of another user defined text frame of the same type
231 * using find() and testing for null.
233 void setDescription(const String &s);
235 StringList fieldList() const;
236 void setText(const String &text);
237 void setText(const StringList &fields);
240 * Searches for the user defined text frame with the description \a description
241 * in \a tag. This returns null if no matching frames were found.
243 static UserTextIdentificationFrame *find(Tag *tag, const String &description);
246 UserTextIdentificationFrame(const ByteVector &data, Header *h);
247 UserTextIdentificationFrame(const TextIdentificationFrame &);
248 UserTextIdentificationFrame &operator=(const UserTextIdentificationFrame &);
252 class UserTextIdentificationFramePrivate;
253 UserTextIdentificationFramePrivate *d;