id3v2frame.h
Go to the documentation of this file.
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_ID3V2FRAME_H
27 #define TAGLIB_ID3V2FRAME_H
28 
29 #include "tstring.h"
30 #include "tbytevector.h"
31 #include "taglib_export.h"
32 
33 namespace TagLib {
34 
35  class StringList;
36  class PropertyMap;
37 
38  namespace ID3v2 {
39 
40  class Tag;
41  class FrameFactory;
42 
44 
54  class TAGLIB_EXPORT Frame
55  {
56  friend class Tag;
57  friend class FrameFactory;
58 
59  public:
60 
66  static Frame *createTextualFrame(const String &key, const StringList &values);
67 
71  virtual ~Frame();
72 
77  ByteVector frameID() const;
78 
82  unsigned int size() const;
83 
92  static unsigned int headerSize(); // BIC: make non-static
93 
99  // BIC: remove
100  static unsigned int headerSize(unsigned int version);
101 
108  void setData(const ByteVector &data);
109 
119  virtual void setText(const String &text);
120 
126  virtual String toString() const = 0;
127 
131  ByteVector render() const;
132 
137  static ByteVector textDelimiter(String::Type t);
138 
144  static const String instrumentPrefix;
149  static const String commentPrefix;
154  static const String lyricsPrefix;
159  static const String urlPrefix;
160 
161  protected:
162  class Header;
163 
171  explicit Frame(const ByteVector &data);
172 
179  Frame(Header *h);
180 
184  Header *header() const;
185 
193  void setHeader(Header *h, bool deleteCurrent = true);
194 
199  void parse(const ByteVector &data);
200 
206  virtual void parseFields(const ByteVector &data) = 0;
207 
212  virtual ByteVector renderFields() const = 0;
213 
219  ByteVector fieldData(const ByteVector &frameData) const;
220 
227  String readStringField(const ByteVector &data, String::Type encoding,
228  int *position = 0);
229 
234  // BIC: remove and make non-static
235  static String::Type checkEncoding(const StringList &fields,
236  String::Type encoding);
237 
244  // BIC: remove and make non-static
245  static String::Type checkEncoding(const StringList &fields,
246  String::Type encoding, unsigned int version);
247 
254  String::Type checkTextEncoding(const StringList &fields,
255  String::Type encoding) const;
256 
257 
264  PropertyMap asProperties() const;
265 
270  static ByteVector keyToFrameID(const String &);
271 
276  static String frameIDToKey(const ByteVector &);
277 
281  static String keyToTXXX(const String &);
282 
286  static String txxxToKey(const String &);
287 
301  static void splitProperties(const PropertyMap &original, PropertyMap &singleFrameProperties,
302  PropertyMap &tiplProperties, PropertyMap &tmclProperties);
303 
304  private:
305  Frame(const Frame &);
306  Frame &operator=(const Frame &);
307 
308  class FramePrivate;
309  friend class FramePrivate;
310  FramePrivate *d;
311  };
312 
314 
327  class TAGLIB_EXPORT Frame::Header
328  {
329  public:
338  TAGLIB_DEPRECATED Header(const ByteVector &data, bool synchSafeInts);
339 
347  explicit Header(const ByteVector &data, unsigned int version = 4);
348 
352  virtual ~Header();
353 
360  TAGLIB_DEPRECATED void setData(const ByteVector &data, bool synchSafeInts);
361 
366  void setData(const ByteVector &data, unsigned int version = 4);
367 
372  ByteVector frameID() const;
373 
382  void setFrameID(const ByteVector &id);
383 
388  unsigned int frameSize() const;
389 
393  void setFrameSize(unsigned int size);
394 
399  unsigned int version() const;
400 
405  void setVersion(unsigned int version);
406 
415  // BIC: make non-static
416  static unsigned int size();
417 
424  // BIC: remove
425  static unsigned int size(unsigned int version);
426 
436  bool tagAlterPreservation() const;
437 
449  void setTagAlterPreservation(bool discard);
450 
456  bool fileAlterPreservation() const;
457 
463  bool readOnly() const;
464 
470  bool groupingIdentity() const;
471 
477  bool compression() const;
478 
484  bool encryption() const;
485 
486 #ifndef DO_NOT_DOCUMENT
487  bool unsycronisation() const;
488 #endif
489 
493  bool unsynchronisation() const;
494 
498  bool dataLengthIndicator() const;
499 
503  ByteVector render() const;
504 
508  TAGLIB_DEPRECATED bool frameAlterPreservation() const;
509 
510  private:
511  Header(const Header &);
512  Header &operator=(const Header &);
513 
514  class HeaderPrivate;
515  HeaderPrivate *d;
516  };
517 
518  }
519 }
520 
521 #endif
A list of strings.
Definition: tstringlist.h:66
A namespace for all TagLib related classes and functions.
Definition: apefile.h:41
Type
Definition: tstring.h:97
#define TAGLIB_DEPRECATED
Definition: taglib.h:54
A map for format-independent <key,valuelist> tag representations.
Definition: tpropertymap.h:134
A byte vector.
Definition: tbytevector.h:66
#define TAGLIB_EXPORT
Definition: taglib_export.h:40
An implementation of ID3v2 headers.
Definition: id3v2header.h:90
ID3v2 frame implementation.
Definition: id3v2frame.h:75
A wide string class suitable for unicode.
Definition: tstring.h:84