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_ID3V2FRAMEFACTORY_H
27
#define TAGLIB_ID3V2FRAMEFACTORY_H
29
#include "taglib_export.h"
30
#include "tbytevector.h"
31
#include "id3v2frame.h"
32
#include "id3v2header.h"
38
class TAGLIB_EXPORT TextIdentificationFrame;
40
//! A factory for creating ID3v2 frames during parsing
43
* This factory abstracts away the frame creation process and instantiates
44
* the appropriate ID3v2::Frame subclasses based on the contents of the
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 or with
51
* MPEG::File::setID3v2FrameFactory() you can implement behavior that will
52
* allow for new ID3v2::Frame subclasses (also provided by you) to be used.
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>).
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()
62
* \see ID3v2::Tag::addFrame()
65
class TAGLIB_EXPORT FrameFactory
68
static FrameFactory *instance();
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
74
* \deprecated Please use the method below that accepts a ID3v2::Header
75
* instance in new code.
77
Frame *createFrame(const ByteVector &data, bool synchSafeInts) const;
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.
84
* \deprecated Please use the method below that accepts a ID3v2::Header
85
* instance in new code.
87
Frame *createFrame(const ByteVector &data, uint version = 4) const;
90
* Create a frame based on \a data. \a tagHeader should be a valid
91
* ID3v2::Header instance.
94
Frame *createFrame(const ByteVector &data, Header *tagHeader) const;
97
* Returns the default text encoding for text frames. If setTextEncoding()
98
* has not been explicitly called this will only be used for new text
99
* frames. However, if this value has been set explicitly all frames will be
100
* converted to this type (unless it's explitly set differently for the
101
* individual frame) when being rendered.
103
* \see setDefaultTextEncoding()
105
String::Type defaultTextEncoding() const;
108
* Set the default text encoding for all text frames that are created to
109
* \a encoding. If no value is set the frames with either default to the
110
* encoding type that was parsed and new frames default to Latin1.
112
* Valid string types for ID3v2 tags are Latin1, UTF8, UTF16 and UTF16BE.
114
* \see defaultTextEncoding()
116
void setDefaultTextEncoding(String::Type encoding);
120
* Constructs a frame factory. Because this is a singleton this method is
121
* protected, but may be used for subclasses.
126
* Destroys the frame factory. In most cases this will never be called (as
127
* is typical of singletons).
129
virtual ~FrameFactory();
132
* This method checks for compliance to the current ID3v2 standard (2.4)
133
* and does nothing in the common case. However if a frame is found that
134
* is not compatible with the current standard, this method either updates
135
* the frame or indicates that it should be discarded.
137
* This method with return true (with or without changes to the frame) if
138
* this frame should be kept or false if it should be discarded.
140
* See the id3v2.4.0-changes.txt document for further information.
142
virtual bool updateFrame(Frame::Header *header) const;
145
FrameFactory(const FrameFactory &);
146
FrameFactory &operator=(const FrameFactory &);
149
* This method is used internally to convert a frame from ID \a from to ID
150
* \a to. If the frame matches the \a from pattern and converts the frame
151
* ID in the \a header or simply does nothing if the frame ID does not match.
153
void convertFrame(const char *from, const char *to,
154
Frame::Header *header) const;
156
void updateGenre(TextIdentificationFrame *frame) const;
158
static FrameFactory *factory;
160
class FrameFactoryPrivate;
161
FrameFactoryPrivate *d;
added
removed
Frameworks/taglib/taglib/taglib/mpeg/id3v2/id3v2framefactory.h
