rtaglib 0.2.3 → 0.3.0

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

@@ -0,0 +1,262 @@
+/***************************************************************************
+    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_FILEREF_H
+#define TAGLIB_FILEREF_H
+
+#include <tfile.h>
+#include <tstringlist.h>
+
+#include "taglib_export.h"
+#include "audioproperties.h"
+
+namespace TagLib {
+
+  class Tag;
+
+  //! This class provides a simple abstraction for creating and handling files
+
+  /*!
+   * FileRef exists to provide a minimal, generic and value-based wrapper around
+   * a File.  It is lightweight and implicitly shared, and as such suitable for
+   * pass-by-value use.  This hides some of the uglier details of TagLib::File
+   * and the non-generic portions of the concrete file implementations.
+   *
+   * This class is useful in a "simple usage" situation where it is desirable
+   * to be able to get and set some of the tag information that is similar
+   * across file types.
+   *
+   * Also note that it is probably a good idea to plug this into your mime
+   * type system rather than using the constructor that accepts a file name using
+   * the FileTypeResolver.
+   *
+   * \see FileTypeResolver
+   * \see addFileTypeResolver()
+   */
+
+  class TAGLIB_EXPORT FileRef
+  {
+  public:
+
+  //! A class for pluggable file type resolution.
+
+  /*!
+   * This class is used to add extend TagLib's very basic file name based file
+   * type resolution.
+   *
+   * This can be accomplished with:
+   *
+   * \code
+   *
+   * class MyFileTypeResolver : FileTypeResolver
+   * {
+   *   TagLib::File *createFile(TagLib::FileName *fileName, bool, AudioProperties::ReadStyle)
+   *   {
+   *     if(someCheckForAnMP3File(fileName))
+   *       return new TagLib::MPEG::File(fileName);
+   *     return 0;
+   *   }
+   * }
+   *
+   * FileRef::addFileTypeResolver(new MyFileTypeResolver);
+   *
+   * \endcode
+   *
+   * Naturally a less contrived example would be slightly more complex.  This
+   * can be used to plug in mime-type detection systems or to add new file types
+   * to TagLib.
+   */
+
+    class TAGLIB_EXPORT FileTypeResolver
+    {
+    public:
+      // do not fix compiler warning about missing virtual destructor
+      // since this would not be binary compatible
+      // let Scott fix it whenever he thinks BIC changes can next be applied
+      /*!
+       * This method must be overridden to provide an additional file type
+       * resolver.  If the resolver is able to determine the file type it should
+       * return a valid File object; if not it should return 0.
+       *
+       * \note The created file is then owned by the FileRef and should not be
+       * deleted.  Deletion will happen automatically when the FileRef passes
+       * out of scope.
+       */
+      virtual File *createFile(FileName fileName,
+                               bool readAudioProperties = true,
+                               AudioProperties::ReadStyle
+                               audioPropertiesStyle = AudioProperties::Average) const = 0;
+    };
+
+    /*!
+     * Creates a null FileRef.
+     */
+    FileRef();
+
+    /*!
+     * Create a FileRef from \a fileName.  If \a readAudioProperties is true then
+     * the audio properties will be read using \a audioPropertiesStyle.  If
+     * \a readAudioProperties is false then \a audioPropertiesStyle will be
+     * ignored.
+     *
+     * Also see the note in the class documentation about why you may not want to
+     * use this method in your application.
+     */
+    explicit FileRef(FileName fileName,
+                     bool readAudioProperties = true,
+                     AudioProperties::ReadStyle
+                     audioPropertiesStyle = AudioProperties::Average);
+
+    /*!
+     * Contruct a FileRef using \a file.  The FileRef now takes ownership of the
+     * pointer and will delete the File when it passes out of scope.
+     */
+    explicit FileRef(File *file);
+
+    /*!
+     * Make a copy of \a ref.
+     */
+    FileRef(const FileRef &ref);
+
+    /*!
+     * Destroys this FileRef instance.
+     */
+    virtual ~FileRef();
+
+    /*!
+     * Returns a pointer to represented file's tag.
+     *
+     * \warning This pointer will become invalid when this FileRef and all
+     * copies pass out of scope.
+     *
+     * \see File::tag()
+     */
+    Tag *tag() const;
+
+    /*!
+     * Returns the audio properties for this FileRef.  If no audio properties
+     * were read then this will returns a null pointer.
+     */
+    AudioProperties *audioProperties() const;
+
+    /*!
+     * Returns a pointer to the file represented by this handler class.
+     *
+     * As a general rule this call should be avoided since if you need to work
+     * with file objects directly, you are probably better served instantiating
+     * the File subclasses (i.e. MPEG::File) manually and working with their APIs.
+     *
+     * This <i>handle</i> exists to provide a minimal, generic and value-based
+     * wrapper around a File.  Accessing the file directly generally indicates
+     * a moving away from this simplicity (and into things beyond the scope of
+     * FileRef).
+     *
+     * \warning This pointer will become invalid when this FileRef and all
+     * copies pass out of scope.
+     */
+    File *file() const;
+
+    /*!
+     * Saves the file.  Returns true on success.
+     */
+    bool save();
+
+    /*!
+     * Adds a FileTypeResolver to the list of those used by TagLib.  Each
+     * additional FileTypeResolver is added to the front of a list of resolvers
+     * that are tried.  If the FileTypeResolver returns zero the next resolver
+     * is tried.
+     *
+     * Returns a pointer to the added resolver (the same one that's passed in --
+     * this is mostly so that static inialializers have something to use for
+     * assignment).
+     *
+     * \see FileTypeResolver
+     */
+    static const FileTypeResolver *addFileTypeResolver(const FileTypeResolver *resolver);
+
+    /*!
+     * As is mentioned elsewhere in this class's documentation, the default file
+     * type resolution code provided by TagLib only works by comparing file
+     * extensions.
+     *
+     * This method returns the list of file extensions that are used by default.
+     *
+     * The extensions are all returned in lowercase, though the comparison used
+     * by TagLib for resolution is case-insensitive.
+     *
+     * \note This does not account for any additional file type resolvers that
+     * are plugged in.  Also note that this is not intended to replace a propper
+     * mime-type resolution system, but is just here for reference.
+     *
+     * \see FileTypeResolver
+     */
+    static StringList defaultFileExtensions();
+
+    /*!
+     * Returns true if the file (and as such other pointers) are null.
+     */
+    bool isNull() const;
+
+    /*!
+     * Assign the file pointed to by \a ref to this FileRef.
+     */
+    FileRef &operator=(const FileRef &ref);
+
+    /*!
+     * Returns true if this FileRef and \a ref point to the same File object.
+     */
+    bool operator==(const FileRef &ref) const;
+
+    /*!
+     * Returns true if this FileRef and \a ref do not point to the same File
+     * object.
+     */
+    bool operator!=(const FileRef &ref) const;
+
+    /*!
+     * A simple implementation of file type guessing.  If \a readAudioProperties
+     * is true then the audio properties will be read using
+     * \a audioPropertiesStyle.  If \a readAudioProperties is false then
+     * \a audioPropertiesStyle will be ignored.
+     *
+     * \note You generally shouldn't use this method, but instead the constructor
+     * directly.
+     *
+     * \deprecated
+     */
+    static File *create(FileName fileName,
+                        bool readAudioProperties = true,
+                        AudioProperties::ReadStyle audioPropertiesStyle = AudioProperties::Average);
+
+
+  private:
+    class FileRefPrivate;
+    FileRefPrivate *d;
+  };
+
+} // namespace TagLib
+
+#endif

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

@@ -0,0 +1,201 @@
+/***************************************************************************
+    copyright            : (C) 2003 by Allan Sandfeld Jensen
+    email                : kde@carewolf.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_FLACFILE_H
+#define TAGLIB_FLACFILE_H
+
+#include "taglib_export.h"
+#include "tfile.h"
+
+#include "flacproperties.h"
+
+namespace TagLib {
+
+  class Tag;
+
+  namespace ID3v2 { class FrameFactory; class Tag; }
+  namespace ID3v1 { class Tag; }
+  namespace Ogg { class XiphComment; }
+
+  //! An implementation of FLAC metadata
+
+  /*!
+   * This is implementation of FLAC metadata for non-Ogg FLAC files.  At some
+   * point when Ogg / FLAC is more common there will be a similar implementation
+   * under the Ogg hiearchy.
+   *
+   * This supports ID3v1, ID3v2 and Xiph style comments as well as reading stream
+   * properties from the file.
+   */
+
+  namespace FLAC {
+
+    //! An implementation of TagLib::File with FLAC specific methods
+
+    /*!
+     * This implements and provides an interface for FLAC files to the
+     * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
+     * the abstract TagLib::File API as well as providing some additional
+     * information specific to FLAC files.
+     */
+
+    class TAGLIB_EXPORT File : public TagLib::File
+    {
+    public:
+      /*!
+       * Contructs a FLAC file from \a file.  If \a readProperties is true the
+       * file's audio properties will also be read using \a propertiesStyle.  If
+       * false, \a propertiesStyle is ignored.
+       *
+       * \deprecated This constructor will be dropped in favor of the one below
+       * in a future version.
+       */
+      File(FileName file, bool readProperties = true,
+           Properties::ReadStyle propertiesStyle = Properties::Average);
+
+      /*!
+       * Contructs a FLAC file from \a file.  If \a readProperties is true the
+       * file's audio properties will also be read using \a propertiesStyle.  If
+       * false, \a propertiesStyle is ignored.
+       *
+       * If this file contains and ID3v2 tag the frames will be created using
+       * \a frameFactory.
+       */
+      // BIC: merge with the above constructor
+      File(FileName file, ID3v2::FrameFactory *frameFactory,
+           bool readProperties = true,
+           Properties::ReadStyle propertiesStyle = Properties::Average);
+
+      /*!
+       * Destroys this instance of the File.
+       */
+      virtual ~File();
+
+      /*!
+       * Returns the Tag for this file.  This will be a union of XiphComment,
+       * ID3v1 and ID3v2 tags.
+       *
+       * \see ID3v2Tag()
+       * \see ID3v1Tag()
+       * \see XiphComment()
+       */
+      virtual TagLib::Tag *tag() const;
+
+      /*!
+       * Returns the FLAC::Properties for this file.  If no audio properties
+       * were read then this will return a null pointer.
+       */
+      virtual Properties *audioProperties() const;
+
+      /*!
+       * Save the file.  This will primarily save the XiphComment, but
+       * will also keep any old ID3-tags up to date. If the file
+       * has no XiphComment, one will be constructed from the ID3-tags.
+       *
+       * This returns true if the save was successful.
+       */
+      virtual bool save();
+
+      /*!
+       * Returns a pointer to the ID3v2 tag of the file.
+       *
+       * If \a create is false (the default) this will return a null pointer
+       * if there is no valid ID3v2 tag.  If \a create is true it will create
+       * an ID3v2 tag if one does not exist.
+       *
+       * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
+       * deleted by the user.  It will be deleted when the file (object) is
+       * destroyed.
+       */
+      ID3v2::Tag *ID3v2Tag(bool create = false);
+
+      /*!
+       * Returns a pointer to the ID3v1 tag of the file.
+       *
+       * If \a create is false (the default) this will return a null pointer
+       * if there is no valid ID3v1 tag.  If \a create is true it will create
+       * an ID3v1 tag if one does not exist.
+       *
+       * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
+       * deleted by the user.  It will be deleted when the file (object) is
+       * destroyed.
+       */
+      ID3v1::Tag *ID3v1Tag(bool create = false);
+
+      /*!
+       * Returns a pointer to the XiphComment for the file.
+       *
+       * If \a create is false (the default) this will return a null pointer
+       * if there is no valid XiphComment.  If \a create is true it will create
+       * a XiphComment if one does not exist.
+       *
+       * \note The Tag <b>is still</b> owned by the FLAC::File and should not be
+       * deleted by the user.  It will be deleted when the file (object) is
+       * destroyed.
+       */
+      Ogg::XiphComment *xiphComment(bool create = false);
+
+      /*!
+       * Set the ID3v2::FrameFactory to something other than the default.  This
+       * can be used to specify the way that ID3v2 frames will be interpreted
+       * when
+       *
+       * \see ID3v2FrameFactory
+       */
+      void setID3v2FrameFactory(const ID3v2::FrameFactory *factory);
+
+      /*!
+       * Returns the block of data used by FLAC::Properties for parsing the
+       * stream properties.
+       *
+       * \deprecated This method will not be public in a future release.
+       */
+      ByteVector streamInfoData(); // BIC: remove
+
+      /*!
+       * Returns the length of the audio-stream, used by FLAC::Properties for
+       * calculating the bitrate.
+       *
+       * \deprecated This method will not be public in a future release.
+       */
+      long streamLength();  // BIC: remove
+
+    private:
+      File(const File &);
+      File &operator=(const File &);
+
+      void read(bool readProperties, Properties::ReadStyle propertiesStyle);
+      void scan();
+      long findID3v2();
+      long findID3v1();
+      ByteVector xiphCommentData() const;
+
+      class FilePrivate;
+      FilePrivate *d;
+    };
+  }
+}
+
+#endif