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_ID3V2FRAMEFACTORY_H
27#define TAGLIB_ID3V2FRAMEFACTORY_H
28
29#include "taglib_export.h"
30#include "tbytevector.h"
31#include "id3v2frame.h"
32#include "id3v2header.h"
33
34namespace TagLib {
35
36 namespace ID3v2 {
37
38 class TextIdentificationFrame;
39
40 //! A factory for creating ID3v2 frames during parsing
41
42 /*!
43 * This factory abstracts away the frame creation process and instantiates
44 * the appropriate ID3v2::Frame subclasses based on the contents of the
45 * data.
46 *
47 * Reimplementing this factory is the key to adding support for frame types
48 * not directly supported by TagLib to your application. To do so you would
49 * subclass this factory reimplement createFrame(). Then by setting your
50 * factory to be the default factory in ID3v2::Tag constructor you can
51 * implement behavior that will allow for new ID3v2::Frame subclasses (also
52 * provided by you) to be used.
53 *
54 * This implements both <i>abstract factory</i> and <i>singleton</i> patterns
55 * of which more information is available on the web and in software design
56 * textbooks (Notably <i>Design Patters</i>).
57 *
58 * \note You do not need to use this factory to create new frames to add to
59 * an ID3v2::Tag. You can instantiate frame subclasses directly (with new)
60 * and add them to a tag using ID3v2::Tag::addFrame()
61 *
62 * \see ID3v2::Tag::addFrame()
63 */
64
65 class TAGLIB_EXPORT FrameFactory
66 {
67 public:
68 static FrameFactory *instance();
69 /*!
70 * Create a frame based on \a data. \a synchSafeInts should only be set
71 * false if we are parsing an old tag (v2.3 or older) that does not support
72 * synchsafe ints.
73 *
74 * \deprecated Please use the method below that accepts a ID3v2::Header
75 * instance in new code.
76 */
77 Frame *createFrame(const ByteVector &data, bool synchSafeInts) const;
78
79 /*!
80 * Create a frame based on \a data. \a version should indicate the ID3v2
81 * version of the tag. As ID3v2.4 is the most current version of the
82 * standard 4 is the default.
83 *
84 * \deprecated Please use the method below that accepts a ID3v2::Header
85 * instance in new code.
86 */
87 Frame *createFrame(const ByteVector &data, unsigned int version = 4) const;
88
89 /*!
90 * Create a frame based on \a data. \a tagHeader should be a valid
91 * ID3v2::Header instance.
92 */
93 // BIC: make virtual
94 Frame *createFrame(const ByteVector &data, Header *tagHeader) const;
95
96 /*!
97 * After a tag has been read, this tries to rebuild some of them
98 * information, most notably the recording date, from frames that
99 * have been deprecated and can't be upgraded directly.
100 */
101 // BIC: Make virtual
102 void rebuildAggregateFrames(ID3v2::Tag *tag) const;
103
104 /*!
105 * Returns the default text encoding for text frames. If setTextEncoding()
106 * has not been explicitly called this will only be used for new text
107 * frames. However, if this value has been set explicitly all frames will be
108 * converted to this type (unless it's explicitly set differently for the
109 * individual frame) when being rendered.
110 *
111 * \see setDefaultTextEncoding()
112 */
113 String::Type defaultTextEncoding() const;
114
115 /*!
116 * Set the default text encoding for all text frames that are created to
117 * \a encoding. If no value is set the frames with either default to the
118 * encoding type that was parsed and new frames default to Latin1.
119 *
120 * Valid string types for ID3v2 tags are Latin1, UTF8, UTF16 and UTF16BE.
121 *
122 * \see defaultTextEncoding()
123 */
124 void setDefaultTextEncoding(String::Type encoding);
125
126 protected:
127 /*!
128 * Constructs a frame factory. Because this is a singleton this method is
129 * protected, but may be used for subclasses.
130 */
131 FrameFactory();
132
133 /*!
134 * Destroys the frame factory.
135 */
136 virtual ~FrameFactory();
137
138 /*!
139 * This method checks for compliance to the current ID3v2 standard (2.4)
140 * and does nothing in the common case. However if a frame is found that
141 * is not compatible with the current standard, this method either updates
142 * the frame or indicates that it should be discarded.
143 *
144 * This method with return true (with or without changes to the frame) if
145 * this frame should be kept or false if it should be discarded.
146 *
147 * See the id3v2.4.0-changes.txt document for further information.
148 */
149 virtual bool updateFrame(Frame::Header *header) const;
150
151 private:
152 FrameFactory(const FrameFactory &);
153 FrameFactory &operator=(const FrameFactory &);
154
155 static FrameFactory factory;
156
157 class FrameFactoryPrivate;
158 FrameFactoryPrivate *d;
159 };
160
161 }
162}
163
164#endif
165