rtaglib 0.2.3 → 0.3.0

data/ext/taglib/taglib-mswin32/include/taglib/id3v2framefactory.h

@@ -0,0 +1,167 @@
+ /***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_ID3V2FRAMEFACTORY_H
+#define TAGLIB_ID3V2FRAMEFACTORY_H
+
+#include "taglib_export.h"
+#include "tbytevector.h"
+#include "id3v2frame.h"
+#include "id3v2header.h"
+
+namespace TagLib {
+
+  namespace ID3v2 {
+
+    class TAGLIB_EXPORT TextIdentificationFrame;
+
+    //! A factory for creating ID3v2 frames during parsing
+
+    /*!
+     * This factory abstracts away the frame creation process and instantiates
+     * the appropriate ID3v2::Frame subclasses based on the contents of the
+     * data.
+     *
+     * Reimplementing this factory is the key to adding support for frame types
+     * not directly supported by TagLib to your application.  To do so you would
+     * subclass this factory reimplement createFrame().  Then by setting your
+     * factory to be the default factory in ID3v2::Tag constructor or with
+     * MPEG::File::setID3v2FrameFactory() you can implement behavior that will
+     * allow for new ID3v2::Frame subclasses (also provided by you) to be used.
+     *
+     * This implements both <i>abstract factory</i> and <i>singleton</i> patterns
+     * of which more information is available on the web and in software design
+     * textbooks (Notably <i>Design Patters</i>).
+     *
+     * \note You do not need to use this factory to create new frames to add to
+     * an ID3v2::Tag.  You can instantiate frame subclasses directly (with new)
+     * and add them to a tag using ID3v2::Tag::addFrame()
+     *
+     * \see ID3v2::Tag::addFrame()
+     */
+
+    class TAGLIB_EXPORT FrameFactory
+    {
+    public:
+      static FrameFactory *instance();
+      /*!
+       * Create a frame based on \a data.  \a synchSafeInts should only be set
+       * false if we are parsing an old tag (v2.3 or older) that does not support
+       * synchsafe ints.
+       *
+       * \deprecated Please use the method below that accepts a ID3v2::Header
+       * instance in new code.
+       */
+      Frame *createFrame(const ByteVector &data, bool synchSafeInts) const;
+
+      /*!
+       * Create a frame based on \a data.  \a version should indicate the ID3v2
+       * version of the tag.  As ID3v2.4 is the most current version of the
+       * standard 4 is the default.
+       *
+       * \deprecated Please use the method below that accepts a ID3v2::Header
+       * instance in new code.
+       */
+      Frame *createFrame(const ByteVector &data, uint version = 4) const;
+
+      /*!
+       * Create a frame based on \a data.  \a tagHeader should be a valid
+       * ID3v2::Header instance.
+       */
+      // BIC: make virtual
+      Frame *createFrame(const ByteVector &data, Header *tagHeader) const;
+
+      /*!
+       * Returns the default text encoding for text frames.  If setTextEncoding()
+       * has not been explicitly called this will only be used for new text
+       * frames.  However, if this value has been set explicitly all frames will be
+       * converted to this type (unless it's explitly set differently for the
+       * individual frame) when being rendered.
+       *
+       * \see setDefaultTextEncoding()
+       */
+      String::Type defaultTextEncoding() const;
+
+      /*!
+       * Set the default text encoding for all text frames that are created to
+       * \a encoding.  If no value is set the frames with either default to the
+       * encoding type that was parsed and new frames default to Latin1.
+       *
+       * Valid string types for ID3v2 tags are Latin1, UTF8, UTF16 and UTF16BE.
+       *
+       * \see defaultTextEncoding()
+       */
+      void setDefaultTextEncoding(String::Type encoding);
+
+    protected:
+      /*!
+       * Constructs a frame factory.  Because this is a singleton this method is
+       * protected, but may be used for subclasses.
+       */
+      FrameFactory();
+
+      /*!
+       * Destroys the frame factory.  In most cases this will never be called (as
+       * is typical of singletons).
+       */
+      virtual ~FrameFactory();
+
+      /*!
+       * This method checks for compliance to the current ID3v2 standard (2.4)
+       * and does nothing in the common case.  However if a frame is found that
+       * is not compatible with the current standard, this method either updates
+       * the frame or indicates that it should be discarded.
+       *
+       * This method with return true (with or without changes to the frame) if
+       * this frame should be kept or false if it should be discarded.
+       *
+       * See the id3v2.4.0-changes.txt document for further information.
+       */
+      virtual bool updateFrame(Frame::Header *header) const;
+
+    private:
+      FrameFactory(const FrameFactory &);
+      FrameFactory &operator=(const FrameFactory &);
+
+      /*!
+       * This method is used internally to convert a frame from ID \a from to ID
+       * \a to.  If the frame matches the \a from pattern and converts the frame
+       * ID in the \a header or simply does nothing if the frame ID does not match.
+       */
+      void convertFrame(const char *from, const char *to,
+                        Frame::Header *header) const;
+
+      void updateGenre(TextIdentificationFrame *frame) const;
+
+      static FrameFactory *factory;
+
+      class FrameFactoryPrivate;
+      FrameFactoryPrivate *d;
+    };
+
+  }
+}
+
+#endif

data/ext/taglib/taglib-mswin32/include/taglib/id3v2header.h

@@ -0,0 +1,175 @@
+/***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_ID3V2HEADER_H
+#define TAGLIB_ID3V2HEADER_H
+
+#include "tbytevector.h"
+#include "taglib_export.h"
+
+namespace TagLib {
+
+  namespace ID3v2 {
+
+    //! An implementation of ID3v2 headers
+
+    /*!
+     * This class implements ID3v2 headers.  It attempts to follow, both
+     * semantically and programatically, the structure specified in
+     * the ID3v2 standard.  The API is based on the properties of ID3v2 headers
+     * specified there.  If any of the terms used in this documentation are
+     * unclear please check the specification in the linked section.
+     * (Structure, <a href="id3v2-structure.html#3.1">3.1</a>)
+     */
+
+    class TAGLIB_EXPORT Header
+    {
+    public:
+      /*!
+       * Constructs an empty ID3v2 header.
+       */
+      Header();
+
+      /*!
+       * Constructs an ID3v2 header based on \a data.  parse() is called
+       * immediately.
+       */
+      Header(const ByteVector &data);
+
+      /*!
+       * Destroys the header.
+       */
+      virtual ~Header();
+
+      /*!
+       * Returns the major version number.  (Note: This is the 4, not the 2 in
+       * ID3v2.4.0.  The 2 is implied.)
+       */
+      uint majorVersion() const;
+
+      /*!
+       * Set the the major version number to \a version.  (Note: This is
+       * the 4, not the 2 in ID3v2.4.0.  The 2 is implied.)
+       * \see majorVersion()
+       *
+       * \note This is used by the internal parser; this will not change the
+       * version which is written and in general should not be called by API
+       * users.
+       */
+      void setMajorVersion(uint version);
+
+      /*!
+       * Returns the revision number.  (Note: This is the 0, not the 4 in
+       * ID3v2.4.0.  The 2 is implied.)
+       */
+      uint revisionNumber() const;
+
+      /*!
+       * Returns true if unsynchronisation has been applied to all frames.
+       */
+      bool unsynchronisation() const;
+
+      /*!
+       * Returns true if an extended header is present in the tag.
+       */
+      bool extendedHeader() const;
+
+      /*!
+       * Returns true if the experimental indicator flag is set.
+       */
+      bool experimentalIndicator() const;
+
+      /*!
+       * Returns true if a footer is present in the tag.
+       */
+      bool footerPresent() const;
+      /*!
+       * Returns the tag size in bytes.  This is the size of the frame content.
+       * The size of the \e entire tag will be this plus the header size (10
+       * bytes) and, if present, the footer size (potentially another 10 bytes).
+       *
+       * \note This is the value as read from the header to which TagLib attempts
+       * to provide an API to; it was not a design decision on the part of TagLib
+       * to not include the mentioned portions of the tag in the \e size.
+       *
+       * \see completeTagSize()
+       */
+      uint tagSize() const;
+
+      /*!
+       * Returns the tag size, including the header and, if present, the footer
+       * size.
+       *
+       * \see tagSize()
+       */
+      uint completeTagSize() const;
+
+      /*!
+       * Set the tag size to \a s.
+       * \see tagSize()
+       */
+      void setTagSize(uint s);
+
+      /*!
+       * Returns the size of the header.  Presently this is always 10 bytes.
+       */
+      static uint size();
+
+      /*!
+       * Returns the string used to identify and ID3v2 tag inside of a file.
+       * Presently this is always "ID3".
+       */
+      static ByteVector fileIdentifier();
+
+      /*!
+       * Sets the data that will be used as the header.  10 bytes, starting from
+       * the beginning of \a data are used.
+       */
+      void setData(const ByteVector &data);
+
+      /*!
+       * Renders the Header back to binary format.
+       */
+      ByteVector render() const;
+
+    protected:
+      /*!
+       * Called by setData() to parse the header data.  It makes this information
+       * available through the public API.
+       */
+      void parse(const ByteVector &data);
+
+    private:
+      Header(const Header &);
+      Header &operator=(const Header &);
+
+      class HeaderPrivate;
+      HeaderPrivate *d;
+    };
+
+  }
+}
+
+#endif

data/ext/taglib/taglib-mswin32/include/taglib/id3v2synchdata.h

@@ -0,0 +1,70 @@
+/***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_ID3V2SYNCHDATA_H
+#define TAGLIB_ID3V2SYNCHDATA_H
+
+#include "tbytevector.h"
+#include "taglib.h"
+
+namespace TagLib {
+
+  namespace ID3v2 {
+
+    //! A few functions for ID3v2 synch safe integer conversion
+
+    /*!
+     * In the ID3v2.4 standard most integer values are encoded as "synch safe"
+     * integers which are encoded in such a way that they will not give false
+     * MPEG syncs and confuse MPEG decoders.  This namespace provides some
+     * methods for converting to and from these values to ByteVectors for
+     * things rendering and parsing ID3v2 data.
+     */
+
+    namespace SynchData
+    {
+      /*!
+       * This returns the unsigned integer value of \a data where \a data is a
+       * ByteVector that contains a \e synchsafe integer (Structure,
+       * <a href="id3v2-structure.html#6.2">6.2</a>).  The default \a length of
+       * 4 is used if another value is not specified.
+       */
+      TAGLIB_EXPORT uint toUInt(const ByteVector &data);
+
+      /*!
+       * Returns a 4 byte (32 bit) synchsafe integer based on \a value.
+       */
+      TAGLIB_EXPORT ByteVector fromUInt(uint value);
+
+      /*!
+       * Convert the data from unsynchronized data to its original format.
+       */
+      TAGLIB_EXPORT ByteVector decode(const ByteVector &input);
+    }
+
+  }
+}
+
+#endif

data/ext/taglib/taglib-mswin32/include/taglib/id3v2tag.h

@@ -0,0 +1,300 @@
+/***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_ID3V2TAG_H
+#define TAGLIB_ID3V2TAG_H
+
+#include "tag.h"
+#include "tbytevector.h"
+#include "tstring.h"
+#include "tlist.h"
+#include "tmap.h"
+#include "taglib_export.h"
+
+#include "id3v2framefactory.h"
+
+namespace TagLib {
+
+  class File;
+
+  //! An ID3v2 implementation
+
+  /*!
+   * This is a relatively complete and flexible framework for working with ID3v2
+   * tags.
+   *
+   * \see ID3v2::Tag
+   */
+
+  namespace ID3v2 {
+
+    class Header;
+    class ExtendedHeader;
+    class Footer;
+
+    typedef List<Frame *> FrameList;
+    typedef Map<ByteVector, FrameList> FrameListMap;
+
+    //! The main class in the ID3v2 implementation
+
+    /*!
+     * This is the main class in the ID3v2 implementation.  It serves two
+     * functions.  This first, as is obvious from the public API, is to provide a
+     * container for the other ID3v2 related classes.  In addition, through the
+     * read() and parse() protected methods, it provides the most basic level of
+     * parsing.  In these methods the ID3v2 tag is extracted from the file and
+     * split into data components.
+     *
+     * ID3v2 tags have several parts, TagLib attempts to provide an interface
+     * for them all.  header(), footer() and extendedHeader() corespond to those
+     * data structures in the ID3v2 standard and the APIs for the classes that
+     * they return attempt to reflect this.
+     *
+     * Also ID3v2 tags are built up from a list of frames, which are in turn
+     * have a header and a list of fields.  TagLib provides two ways of accessing
+     * the list of frames that are in a given ID3v2 tag.  The first is simply
+     * via the frameList() method.  This is just a list of pointers to the frames.
+     * The second is a map from the frame type -- i.e. "COMM" for comments -- and
+     * a list of frames of that type.  (In some cases ID3v2 allows for multiple
+     * frames of the same type, hence this being a map to a list rather than just
+     * a map to an individual frame.)
+     *
+     * More information on the structure of frames can be found in the ID3v2::Frame
+     * class.
+     *
+     * read() and parse() pass binary data to the other ID3v2 class structures,
+     * they do not handle parsing of flags or fields, for instace.  Those are
+     * handled by similar functions within those classes.
+     *
+     * \note All pointers to data structures within the tag will become invalid
+     * when the tag is destroyed.
+     *
+     * \warning Dealing with the nasty details of ID3v2 is not for the faint of
+     * heart and should not be done without much meditation on the spec.  It's
+     * rather long, but if you're planning on messing with this class and others
+     * that deal with the details of ID3v2 (rather than the nice, safe, abstract
+     * TagLib::Tag and friends), it's worth your time to familiarize yourself
+     * with said spec (which is distrubuted with the TagLib sources).  TagLib
+     * tries to do most of the work, but with a little luck, you can still
+     * convince it to generate invalid ID3v2 tags.  The APIs for ID3v2 assume a
+     * working knowledge of ID3v2 structure.  You're been warned.
+     */
+
+    class TAGLIB_EXPORT Tag : public TagLib::Tag
+    {
+    public:
+      /*!
+       * Constructs an empty ID3v2 tag.
+       *
+       * \note You must create at least one frame for this tag to be valid.
+       */
+      Tag();
+
+      /*!
+       * Constructs an ID3v2 tag read from \a file starting at \a tagOffset.
+       * \a factory specifies which FrameFactory will be used for the
+       * construction of new frames.
+       *
+       * \note You should be able to ignore the \a factory parameter in almost
+       * all situations.  You would want to specify your own FrameFactory
+       * subclass in the case that you are extending TagLib to support additional
+       * frame types, which would be incorperated into your factory.
+       *
+       * \see FrameFactory
+       */
+      Tag(File *file, long tagOffset,
+          const FrameFactory *factory = FrameFactory::instance());
+
+      /*!
+       * Destroys this Tag instance.
+       */
+      virtual ~Tag();
+
+      // Reimplementations.
+
+      virtual String title() const;
+      virtual String artist() const;
+      virtual String album() const;
+      virtual String comment() const;
+      virtual String genre() const;
+      virtual uint year() const;
+      virtual uint track() const;
+
+      virtual void setTitle(const String &s);
+      virtual void setArtist(const String &s);
+      virtual void setAlbum(const String &s);
+      virtual void setComment(const String &s);
+      virtual void setGenre(const String &s);
+      virtual void setYear(uint i);
+      virtual void setTrack(uint i);
+
+      virtual bool isEmpty() const;
+
+      /*!
+       * Returns a pointer to the tag's header.
+       */
+      Header *header() const;
+
+      /*!
+       * Returns a pointer to the tag's extended header or null if there is no
+       * extended header.
+       */
+      ExtendedHeader *extendedHeader() const;
+
+      /*!
+       * Returns a pointer to the tag's footer or null if there is no footer.
+       *
+       * \deprecated I don't see any reason to keep this around since there's
+       * nothing useful to be retrieved from the footer, but well, again, I'm
+       * prone to change my mind, so this gets to stay around until near a
+       * release.
+       */
+      Footer *footer() const;
+
+      /*!
+       * Returns a reference to the frame list map.  This is an FrameListMap of
+       * all of the frames in the tag.
+       *
+       * This is the most convenient structure for accessing the tag's frames.
+       * Many frame types allow multiple instances of the same frame type so this
+       * is a map of lists.  In most cases however there will only be a single
+       * frame of a certain type.
+       *
+       * Let's say for instance that you wanted to access the frame for total
+       * beats per minute -- the TBPM frame.
+       *
+       * \code
+       * TagLib::MPEG::File f("foo.mp3");
+       *
+       * // Check to make sure that it has an ID3v2 tag
+       *
+       * if(f.ID3v2Tag()) {
+       *
+       *   // Get the list of frames for a specific frame type
+       *
+       *   TagLib::ID3v2::FrameList l = f.ID3v2Tag()->frameListMap()["TBPM"];
+       *
+       *   if(!l.isEmpty())
+       *     std::cout << l.front()->toString() << std::endl;
+       * }
+       *
+       * \endcode
+       *
+       * \warning You should not modify this data structure directly, instead
+       * use addFrame() and removeFrame().
+       *
+       * \see frameList()
+       */
+      const FrameListMap &frameListMap() const;
+
+      /*!
+       * Returns a reference to the frame list.  This is an FrameList of all of
+       * the frames in the tag in the order that they were parsed.
+       *
+       * This can be useful if for example you want iterate over the tag's frames
+       * in the order that they occur in the tag.
+       *
+       * \warning You should not modify this data structure directly, instead
+       * use addFrame() and removeFrame().
+       */
+      const FrameList &frameList() const;
+
+      /*!
+       * Returns the frame list for frames with the id \a frameID or an empty
+       * list if there are no frames of that type.  This is just a convenience
+       * and is equivalent to:
+       *
+       * \code
+       * frameListMap()[frameID];
+       * \endcode
+       *
+       * \see frameListMap()
+       */
+      const FrameList &frameList(const ByteVector &frameID) const;
+
+      /*!
+       * Add a frame to the tag.  At this point the tag takes ownership of
+       * the frame and will handle freeing its memory.
+       *
+       * \note Using this method will invalidate any pointers on the list
+       * returned by frameList()
+       */
+      void addFrame(Frame *frame);
+
+      /*!
+       * Remove a frame from the tag.  If \a del is true the frame's memory
+       * will be freed; if it is false, it must be deleted by the user.
+       *
+       * \note Using this method will invalidate any pointers on the list
+       * returned by frameList()
+       */
+      void removeFrame(Frame *frame, bool del = true);
+
+      /*!
+       * Remove all frames of type \a id from the tag and free their memory.
+       *
+       * \note Using this method will invalidate any pointers on the list
+       * returned by frameList()
+       */
+      void removeFrames(const ByteVector &id);
+
+      /*!
+       * Render the tag back to binary data, suitable to be written to disk.
+       */
+      ByteVector render() const;
+
+    protected:
+      /*!
+       * Reads data from the file specified in the constructor.  It does basic
+       * parsing of the data in the largest chunks.  It partitions the tag into
+       * the Header, the body of the tag  (which contains the ExtendedHeader and
+       * frames) and Footer.
+       */
+      void read();
+
+      /*!
+       * This is called by read to parse the body of the tag.  It determines if an
+       * extended header exists and adds frames to the FrameListMap.
+       */
+      void parse(const ByteVector &data);
+
+      /*!
+       * Sets the value of the text frame with the Frame ID \a id to \a value.
+       * If the frame does not exist, it is created.
+       */
+      void setTextFrame(const ByteVector &id, const String &value);
+
+    private:
+      Tag(const Tag &);
+      Tag &operator=(const Tag &);
+
+      class TagPrivate;
+      TagPrivate *d;
+    };
+
+  }
+}
+
+#endif