1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : [email protected] 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 34 namespace 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 TAGLIB_DEPRECATED 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 TAGLIB_DEPRECATED Frame *createFrame(const ByteVector &data, unsigned int version = 4) const; 88 89 /*! 90 * \deprecated 91 */ 92 // BIC: remove 93 Frame *createFrame(const ByteVector &data, Header *tagHeader) const; 94 /*! 95 * Create a frame based on \a data. \a tagHeader should be a valid 96 * ID3v2::Header instance. 97 */ 98 // BIC: make virtual 99 Frame *createFrame(const ByteVector &data, const Header *tagHeader) const; 100 101 /*! 102 * After a tag has been read, this tries to rebuild some of them 103 * information, most notably the recording date, from frames that 104 * have been deprecated and can't be upgraded directly. 105 */ 106 // BIC: Make virtual 107 void rebuildAggregateFrames(ID3v2::Tag *tag) const; 108 109 /*! 110 * Returns the default text encoding for text frames. If setTextEncoding() 111 * has not been explicitly called this will only be used for new text 112 * frames. However, if this value has been set explicitly all frames will be 113 * converted to this type (unless it's explicitly set differently for the 114 * individual frame) when being rendered. 115 * 116 * \see setDefaultTextEncoding() 117 */ 118 String::Type defaultTextEncoding() const; 119 120 /*! 121 * Set the default text encoding for all text frames that are created to 122 * \a encoding. If no value is set the frames with either default to the 123 * encoding type that was parsed and new frames default to Latin1. 124 * 125 * Valid string types for ID3v2 tags are Latin1, UTF8, UTF16 and UTF16BE. 126 * 127 * \see defaultTextEncoding() 128 */ 129 void setDefaultTextEncoding(String::Type encoding); 130 131 protected: 132 /*! 133 * Constructs a frame factory. Because this is a singleton this method is 134 * protected, but may be used for subclasses. 135 */ 136 FrameFactory(); 137 138 /*! 139 * Destroys the frame factory. 140 */ 141 virtual ~FrameFactory(); 142 143 /*! 144 * This method checks for compliance to the current ID3v2 standard (2.4) 145 * and does nothing in the common case. However if a frame is found that 146 * is not compatible with the current standard, this method either updates 147 * the frame or indicates that it should be discarded. 148 * 149 * This method with return true (with or without changes to the frame) if 150 * this frame should be kept or false if it should be discarded. 151 * 152 * See the id3v2.4.0-changes.txt document for further information. 153 */ 154 virtual bool updateFrame(Frame::Header *header) const; 155 156 private: 157 FrameFactory(const FrameFactory &); 158 FrameFactory &operator=(const FrameFactory &); 159 160 static FrameFactory factory; 161 162 class FrameFactoryPrivate; 163 FrameFactoryPrivate *d; 164 }; 165 166 } 167 } 168 169 #endif 170