git.maemo.org Git - someplayer/blob - src/taglib/flac/flacfile.h

   1 /***************************************************************************
   2     copyright            : (C) 2003 by Allan Sandfeld Jensen
   3     email                : kde@carewolf.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_FLACFILE_H
  27 #define TAGLIB_FLACFILE_H
  28
  29 #include "taglib_export.h"
  30 #include "tfile.h"
  31
  32 #include "flacproperties.h"
  33
  34 namespace TagLib {
  35
  36   class Tag;
  37
  38   namespace ID3v2 { class FrameFactory; class Tag; }
  39   namespace ID3v1 { class Tag; }
  40   namespace Ogg { class XiphComment; }
  41
  42   //! An implementation of FLAC metadata
  43
  44   /*!
  45    * This is implementation of FLAC metadata for non-Ogg FLAC files.  At some
  46    * point when Ogg / FLAC is more common there will be a similar implementation
  47    * under the Ogg hiearchy.
  48    *
  49    * This supports ID3v1, ID3v2 and Xiph style comments as well as reading stream
  50    * properties from the file.
  51    */
  52
  53   namespace FLAC {
  54
  55     //! An implementation of TagLib::File with FLAC specific methods
  56
  57     /*!
  58      * This implements and provides an interface for FLAC files to the
  59      * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
  60      * the abstract TagLib::File API as well as providing some additional
  61      * information specific to FLAC files.
  62      */
  63
  64     class TAGLIB_EXPORT File : public TagLib::File
  65     {
  66     public:
  67       /*!
  68        * Contructs a FLAC file from \a file.  If \a readProperties is true the
  69        * file's audio properties will also be read using \a propertiesStyle.  If
  70        * false, \a propertiesStyle is ignored.
  71        *
  72        * \deprecated This constructor will be dropped in favor of the one below
  73        * in a future version.
  74        */
  75       File(FileName file, bool readProperties = true,
  76            Properties::ReadStyle propertiesStyle = Properties::Average);
  77
  78       /*!
  79        * Contructs a FLAC file from \a file.  If \a readProperties is true the
  80        * file's audio properties will also be read using \a propertiesStyle.  If
  81        * false, \a propertiesStyle is ignored.
  82        *
  83        * If this file contains and ID3v2 tag the frames will be created using
  84        * \a frameFactory.
  85        */
  86       // BIC: merge with the above constructor
  87       File(FileName file, ID3v2::FrameFactory *frameFactory,
  88            bool readProperties = true,
  89            Properties::ReadStyle propertiesStyle = Properties::Average);
  90
  91       /*!
  92        * Destroys this instance of the File.
  93        */
  94       virtual ~File();
  95
  96       /*!
  97        * Returns the Tag for this file.  This will be a union of XiphComment,
  98        * ID3v1 and ID3v2 tags.
  99        *
 100        * \see ID3v2Tag()
 101        * \see ID3v1Tag()
 102        * \see XiphComment()
 103        */
 104       virtual TagLib::Tag *tag() const;
 105
 106       /*!
 107        * Returns the FLAC::Properties for this file.  If no audio properties
 108        * were read then this will return a null pointer.
 109        */
 110       virtual Properties *audioProperties() const;
 111
 112       /*!
 113        * Save the file.  This will primarily save the XiphComment, but
 114        * will also keep any old ID3-tags up to date. If the file
 115        * has no XiphComment, one will be constructed from the ID3-tags.
 116        *
 117        * This returns true if the save was successful.
 118        */
 119       virtual bool save();
 120
 121       /*!
 122        * Returns a pointer to the ID3v2 tag of the file.
 123        *
 124        * If \a create is false (the default) this will return a null pointer
 125        * if there is no valid ID3v2 tag.  If \a create is true it will create
 126        * an ID3v2 tag if one does not exist.
 127        *
 128        * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
 129        * deleted by the user.  It will be deleted when the file (object) is
 130        * destroyed.
 131        */
 132       ID3v2::Tag *ID3v2Tag(bool create = false);
 133
 134       /*!
 135        * Returns a pointer to the ID3v1 tag of the file.
 136        *
 137        * If \a create is false (the default) this will return a null pointer
 138        * if there is no valid ID3v1 tag.  If \a create is true it will create
 139        * an ID3v1 tag if one does not exist.
 140        *
 141        * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
 142        * deleted by the user.  It will be deleted when the file (object) is
 143        * destroyed.
 144        */
 145       ID3v1::Tag *ID3v1Tag(bool create = false);
 146
 147       /*!
 148        * Returns a pointer to the XiphComment for the file.
 149        *
 150        * If \a create is false (the default) this will return a null pointer
 151        * if there is no valid XiphComment.  If \a create is true it will create
 152        * a XiphComment if one does not exist.
 153        *
 154        * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
 155        * deleted by the user.  It will be deleted when the file (object) is
 156        * destroyed.
 157        */
 158       Ogg::XiphComment *xiphComment(bool create = false);
 159
 160       /*!
 161        * Set the ID3v2::FrameFactory to something other than the default.  This
 162        * can be used to specify the way that ID3v2 frames will be interpreted
 163        * when
 164        *
 165        * \see ID3v2FrameFactory
 166        */
 167       void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
 168
 169       /*!
 170        * Returns the block of data used by FLAC::Properties for parsing the
 171        * stream properties.
 172        *
 173        * \deprecated This method will not be public in a future release.
 174        */
 175       ByteVector streamInfoData(); // BIC: remove
 176
 177       /*!
 178        * Returns the length of the audio-stream, used by FLAC::Properties for
 179        * calculating the bitrate.
 180        *
 181        * \deprecated This method will not be public in a future release.
 182        */
 183       long streamLength();  // BIC: remove
 184
 185     private:
 186       File(const File &);
 187       File &operator=(const File &);
 188
 189       void read(bool readProperties, Properties::ReadStyle propertiesStyle);
 190       void scan();
 191       long findID3v2();
 192       long findID3v1();
 193       ByteVector xiphCommentData() const;
 194       long findPaddingBreak(long nextPageOffset, long targetOffset, bool *isLast);
 195
 196       class FilePrivate;
 197       FilePrivate *d;
 198     };
 199   }
 200 }
 201
 202 #endif