← Back to branch summary

~ubuntu-branches/ubuntu/utopic/ardour3/utopic

« back to all changes in this revision

Viewing changes to libs/taglib/taglib/mpeg/id3v2/frames/textidentificationframe.h

  • Committer: Package Import Robot
  • Author(s): Felipe Sateler
  • Date: 2013-09-21 19:05:02 UTC
  • Revision ID: package-import@ubuntu.com-20130921190502-8gsftrku6jnzhd7v
Tags: upstream-3.4~dfsg
Import upstream version 3.4~dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/taglib/taglib/mpeg/id3v2/frames/textidentificationframe.h
 
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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
 
19
 *   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_TEXTIDENTIFICATIONFRAME_H
 
27
#define TAGLIB_TEXTIDENTIFICATIONFRAME_H
 
28
 
 
29
#include <tstringlist.h>
 
30
#include "taglib_export.h"
 
31
 
 
32
#include <id3v2frame.h>
 
33
 
 
34
namespace TagLib {
 
35
 
 
36
  namespace ID3v2 {
 
37
 
 
38
    class Tag;
 
39
 
 
40
    //! An ID3v2 text identification frame implementation
 
41
 
 
42
    /*!
 
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:
 
46
     *
 
47
     * <ul>
 
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>
 
93
     * </ul>
 
94
     *
 
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.
 
98
     *
 
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).
 
102
     */
 
103
 
 
104
    class TAGLIB_EXPORT TextIdentificationFrame : public Frame
 
105
    {
 
106
      friend class FrameFactory;
 
107
 
 
108
    public:
 
109
      /*!
 
110
       * Construct an empty frame of type \a type.  Uses \a encoding as the
 
111
       * default text encoding.
 
112
       *
 
113
       * \note In this case you must specify the text encoding as it
 
114
       * resolves the ambiguity between constructors.
 
115
       *
 
116
       * \note Please see the note in the class description regarding Latin1.
 
117
       */
 
118
      TextIdentificationFrame(const ByteVector &type, String::Type encoding);
 
119
 
 
120
      /*!
 
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.
 
123
       */
 
124
      explicit TextIdentificationFrame(const ByteVector &data);
 
125
 
 
126
      /*!
 
127
       * Destroys this TextIdentificationFrame instance.
 
128
       */
 
129
      virtual ~TextIdentificationFrame();
 
130
 
 
131
      /*!
 
132
       * Text identification frames are a list of string fields.
 
133
       *
 
134
       * This function will accept either a StringList or a String (using the
 
135
       * StringList constructor that accepts a single String).
 
136
       *
 
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.
 
140
       */
 
141
      void setText(const StringList &l);
 
142
 
 
143
      // Reimplementations.
 
144
 
 
145
      virtual void setText(const String &s);
 
146
      virtual String toString() const;
 
147
 
 
148
      /*!
 
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.
 
152
       *
 
153
       * \note Please see the note in the class description regarding Latin1.
 
154
       *
 
155
       * \see setTextEncoding()
 
156
       * \see render()
 
157
       */
 
158
      String::Type textEncoding() const;
 
159
 
 
160
      /*!
 
161
       * Sets the text encoding to be used when rendering this frame to
 
162
       * \a encoding.
 
163
       *
 
164
       * \note Please see the note in the class description regarding Latin1.
 
165
       *
 
166
       * \see textEncoding()
 
167
       * \see render()
 
168
       */
 
169
      void setTextEncoding(String::Type encoding);
 
170
 
 
171
      /*!
 
172
       * Returns a list of the strings in this frame.
 
173
       */
 
174
      StringList fieldList() const;
 
175
 
 
176
    protected:
 
177
      // Reimplementations.
 
178
 
 
179
      virtual void parseFields(const ByteVector &data);
 
180
      virtual ByteVector renderFields() const;
 
181
 
 
182
      /*!
 
183
       * The constructor used by the FrameFactory.
 
184
       */
 
185
      TextIdentificationFrame(const ByteVector &data, Header *h);
 
186
 
 
187
    private:
 
188
      TextIdentificationFrame(const TextIdentificationFrame &);
 
189
      TextIdentificationFrame &operator=(const TextIdentificationFrame &);
 
190
 
 
191
      class TextIdentificationFramePrivate;
 
192
      TextIdentificationFramePrivate *d;
 
193
    };
 
194
 
 
195
    /*!
 
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.
 
199
     *
 
200
     * This description identifies the frame and must be unique.
 
201
     */
 
202
 
 
203
    //! An ID3v2 custom text identification frame implementationx
 
204
 
 
205
    class TAGLIB_EXPORT UserTextIdentificationFrame : public TextIdentificationFrame
 
206
    {
 
207
      friend class FrameFactory;
 
208
 
 
209
    public:
 
210
      /*!
 
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.
 
213
       */
 
214
      explicit UserTextIdentificationFrame(String::Type encoding = String::Latin1);
 
215
 
 
216
      /*!
 
217
       * Creates a frame based on \a data.
 
218
       */
 
219
      explicit UserTextIdentificationFrame(const ByteVector &data);
 
220
 
 
221
      virtual String toString() const;
 
222
 
 
223
      /*!
 
224
       * Returns the description for this frame.
 
225
       */
 
226
      String description() const;
 
227
 
 
228
      /*!
 
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.
 
232
       */
 
233
      void setDescription(const String &s);
 
234
 
 
235
      StringList fieldList() const;
 
236
      void setText(const String &text);
 
237
      void setText(const StringList &fields);
 
238
 
 
239
      /*!
 
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.
 
242
       */
 
243
      static UserTextIdentificationFrame *find(Tag *tag, const String &description);
 
244
 
 
245
    private:
 
246
      UserTextIdentificationFrame(const ByteVector &data, Header *h);
 
247
      UserTextIdentificationFrame(const TextIdentificationFrame &);
 
248
      UserTextIdentificationFrame &operator=(const UserTextIdentificationFrame &);
 
249
 
 
250
      void checkFields();
 
251
 
 
252
      class UserTextIdentificationFramePrivate;
 
253
      UserTextIdentificationFramePrivate *d;
 
254
    };
 
255
 
 
256
  }
 
257
}
 
258
#endif