git.maemo.org Git - someplayer/blob - src/taglib/mpeg/id3v2/id3v2framefactory.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_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 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.
  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, uint 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        * 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.
 102        *
 103        * \see setDefaultTextEncoding()
 104        */
 105       String::Type defaultTextEncoding() const;
 106
 107       /*!
 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.
 111        *
 112        * Valid string types for ID3v2 tags are Latin1, UTF8, UTF16 and UTF16BE.
 113        *
 114        * \see defaultTextEncoding()
 115        */
 116       void setDefaultTextEncoding(String::Type encoding);
 117
 118     protected:
 119       /*!
 120        * Constructs a frame factory.  Because this is a singleton this method is
 121        * protected, but may be used for subclasses.
 122        */
 123       FrameFactory();
 124
 125       /*!
 126        * Destroys the frame factory.  In most cases this will never be called (as
 127        * is typical of singletons).
 128        */
 129       virtual ~FrameFactory();
 130
 131       /*!
 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.
 136        *
 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.
 139        *
 140        * See the id3v2.4.0-changes.txt document for further information.
 141        */
 142       virtual bool updateFrame(Frame::Header *header) const;
 143
 144     private:
 145       FrameFactory(const FrameFactory &);
 146       FrameFactory &operator=(const FrameFactory &);
 147
 148       /*!
 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.
 152        */
 153       void convertFrame(const char *from, const char *to,
 154                         Frame::Header *header) const;
 155
 156       void updateGenre(TextIdentificationFrame *frame) const;
 157
 158       static FrameFactory *factory;
 159
 160       class FrameFactoryPrivate;
 161       FrameFactoryPrivate *d;
 162     };
 163
 164   }
 165 }
 166
 167 #endif