/***************************************************************************
    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., 51 Franklin Street, Fifth Floor, Boston, MA         *
 *   02110-1301  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;

    //! An abstraction for the ISO-8859-1 string to data encoding in ID3v2 tags.

    /*!
     * ID3v2 tag can store strings in ISO-8859-1 (Latin1), and TagLib only
     * supports genuine ISO-8859-1 by default.  However, in practice, non
     * ISO-8859-1 encodings are often used instead of ISO-8859-1, such as
     * Windows-1252 for western languages, Shift_JIS for Japanese and so on.
     *
     * Here is an option to read such tags by subclassing this class,
     * reimplementing parse() and setting your reimplementation as the default
     * with ID3v2::Tag::setStringHandler().
     *
     * \note Writing non-ISO-8859-1 tags is not implemented intentionally.
     * Use UTF-16 or UTF-8 instead.
     *
     * \see ID3v2::Tag::setStringHandler()
     */
    class TAGLIB_EXPORT Latin1StringHandler
    {
    public:
      Latin1StringHandler();
      virtual ~Latin1StringHandler();

      /*!
       * Decode a string from \a data.  The default implementation assumes that
       * \a data is an ISO-8859-1 (Latin1) character array.
       */
      virtual String parse(const ByteVector &data) const;
    };

    //! 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() correspond 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 instance.  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 distributed 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 incorporated 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 unsigned int year() const;
      virtual unsigned int 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(unsigned int i);
      virtual void setTrack(unsigned int 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);

      /*!
       * Implements the unified property interface -- export function.
       * This function does some work to translate the hard-specified ID3v2
       * frame types into a free-form string-to-stringlist PropertyMap:
       *  - if ID3v2 frame ID is known by Frame::frameIDToKey(), the returned
       *    key is used
       *  - if the frame ID is "TXXX" (user text frame), the description() is
       *    used as key
       *  - if the frame ID is "WXXX" (user url frame),
       *    - if the description is empty or "URL", the key "URL" is used
       *    - otherwise, the key "URL:<description>" is used;
       *  - if the frame ID is "COMM" (comments frame),
       *    - if the description is empty or "COMMENT", the key "COMMENT"
       *      is used
       *    - otherwise, the key "COMMENT:<description>" is used;
       *  - if the frame ID is "USLT" (unsynchronized lyrics),
       *    - if the description is empty or "LYRICS", the key "LYRICS" is used
       *    - otherwise, the key "LYRICS:<description>" is used;
       *  - if the frame ID is "TIPL" (involved peoples list), and if all the
       *    roles defined in the frame are known in TextIdentificationFrame::involvedPeopleMap(),
       *    then "<role>=<name>" will be contained in the returned obejct for each
       *  - if the frame ID is "TMCL" (musician credit list), then
       *    "PERFORMER:<instrument>=<name>" will be contained in the returned
       *    PropertyMap for each defined musician
       *  In any other case, the unsupportedData() of the returned object will contain
       *  the frame's ID and, in case of a frame ID which is allowed to appear more than
       *  once, the description, separated by a "/".
       *
       */
      PropertyMap properties() const;

      /*!
       * Removes unsupported frames given by \a properties. The elements of
       * \a properties must be taken from properties().unsupportedData(); they
       * are of one of the following forms:
       *  - a four-character frame ID, if the ID3 specification allows only one
       *    frame with that ID (thus, the frame is uniquely determined)
       *  - frameID + "/" + description(), when the ID is one of "TXXX", "WXXX",
       *    "COMM", or "USLT",
       *  - "UNKNOWN/" + frameID, for frames that could not be parsed by TagLib.
       *    In that case, *all* unknown frames with the given ID will be removed.
       */
      void removeUnsupportedProperties(const StringList &properties);

      /*!
       * Implements the unified property interface -- import function.
       * See the comments in properties().
       */
      PropertyMap setProperties(const PropertyMap &);

      /*!
       * Render the tag back to binary data, suitable to be written to disk.
       */
      ByteVector render() const;

      /*!
       * Render the tag back to binary data, suitable to be written to disk.
       *
       * The \a version parameter specifies the version of the rendered
       * ID3v2 tag. It can be either 4 or 3.
       */
      // BIC: combine with the above method
      ByteVector render(int version) const;

      /*!
       * Gets the current string handler that decides how the "Latin-1" data
       * will be converted to and from binary data.
       *
       * \see Latin1StringHandler
       */
      static Latin1StringHandler const *latin1StringHandler();

      /*!
       * Sets the string handler that decides how the "Latin-1" data will be
       * converted to and from binary data.
       * If the parameter \a handler is null, the previous handler is
       * released and default ISO-8859-1 handler is restored.
       *
       * \note The caller is responsible for deleting the previous handler
       * as needed after it is released.
       *
       * \see Latin1StringHandler
       */
      static void setLatin1StringHandler(const Latin1StringHandler *handler);

    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);

      void downgradeFrames(FrameList *existingFrames, FrameList *newFrames) const;

    private:
      Tag(const Tag &);
      Tag &operator=(const Tag &);

      class TagPrivate;
      TagPrivate *d;
    };

  }
}

#endif