libs/taglib/taglib/fileref.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_FILEREF_H
  27 #define TAGLIB_FILEREF_H
  28
  29 #include <tfile.h>
  30 #include <tstringlist.h>
  31
  32 #include "taglib_export.h"
  33 #include "audioproperties.h"
  34
  35 namespace TagLib {
  36
  37   class Tag;
  38
  39   //! This class provides a simple abstraction for creating and handling files
  40
  41   /*!
  42    * FileRef exists to provide a minimal, generic and value-based wrapper around
  43    * a File.  It is lightweight and implicitly shared, and as such suitable for
  44    * pass-by-value use.  This hides some of the uglier details of TagLib::File
  45    * and the non-generic portions of the concrete file implementations.
  46    *
  47    * This class is useful in a "simple usage" situation where it is desirable
  48    * to be able to get and set some of the tag information that is similar
  49    * across file types.
  50    *
  51    * Also note that it is probably a good idea to plug this into your mime
  52    * type system rather than using the constructor that accepts a file name using
  53    * the FileTypeResolver.
  54    *
  55    * \see FileTypeResolver
  56    * \see addFileTypeResolver()
  57    */
  58
  59   class TAGLIB_EXPORT FileRef
  60   {
  61   public:
  62
  63   //! A class for pluggable file type resolution.
  64
  65   /*!
  66    * This class is used to add extend TagLib's very basic file name based file
  67    * type resolution.
  68    *
  69    * This can be accomplished with:
  70    *
  71    * \code
  72    *
  73    * class MyFileTypeResolver : FileTypeResolver
  74    * {
  75    *   TagLib::File *createFile(TagLib::FileName *fileName, bool, AudioProperties::ReadStyle)
  76    *   {
  77    *     if(someCheckForAnMP3File(fileName))
  78    *       return new TagLib::MPEG::File(fileName);
  79    *     return 0;
  80    *   }
  81    * }
  82    *
  83    * FileRef::addFileTypeResolver(new MyFileTypeResolver);
  84    *
  85    * \endcode
  86    *
  87    * Naturally a less contrived example would be slightly more complex.  This
  88    * can be used to plug in mime-type detection systems or to add new file types
  89    * to TagLib.
  90    */
  91
  92     class TAGLIB_EXPORT FileTypeResolver
  93     {
  94     public:
  95       // do not fix compiler warning about missing virtual destructor
  96       // since this would not be binary compatible
  97       // let Scott fix it whenever he thinks BIC changes can next be applied
  98       /*!
  99        * This method must be overridden to provide an additional file type
 100        * resolver.  If the resolver is able to determine the file type it should
 101        * return a valid File object; if not it should return 0.
 102        *
 103        * \note The created file is then owned by the FileRef and should not be
 104        * deleted.  Deletion will happen automatically when the FileRef passes
 105        * out of scope.
 106        */
 107       virtual File *createFile(FileName fileName,
 108                                bool readAudioProperties = true,
 109                                AudioProperties::ReadStyle
 110                                audioPropertiesStyle = AudioProperties::Average) const = 0;
 111       virtual ~FileTypeResolver() {}
 112     };
 113
 114     /*!
 115      * Creates a null FileRef.
 116      */
 117     FileRef();
 118
 119     /*!
 120      * Create a FileRef from \a fileName.  If \a readAudioProperties is true then
 121      * the audio properties will be read using \a audioPropertiesStyle.  If
 122      * \a readAudioProperties is false then \a audioPropertiesStyle will be
 123      * ignored.
 124      *
 125      * Also see the note in the class documentation about why you may not want to
 126      * use this method in your application.
 127      */
 128     explicit FileRef(FileName fileName,
 129                      bool readAudioProperties = true,
 130                      AudioProperties::ReadStyle
 131                      audioPropertiesStyle = AudioProperties::Average);
 132
 133     /*!
 134      * Contruct a FileRef using \a file.  The FileRef now takes ownership of the
 135      * pointer and will delete the File when it passes out of scope.
 136      */
 137     explicit FileRef(File *file);
 138
 139     /*!
 140      * Make a copy of \a ref.
 141      */
 142     FileRef(const FileRef &ref);
 143
 144     /*!
 145      * Destroys this FileRef instance.
 146      */
 147     virtual ~FileRef();
 148
 149     /*!
 150      * Returns a pointer to represented file's tag.
 151      *
 152      * \warning This pointer will become invalid when this FileRef and all
 153      * copies pass out of scope.
 154      *
 155      * \see File::tag()
 156      */
 157     Tag *tag() const;
 158
 159     /*!
 160      * Returns the audio properties for this FileRef.  If no audio properties
 161      * were read then this will returns a null pointer.
 162      */
 163     AudioProperties *audioProperties() const;
 164
 165     /*!
 166      * Returns a pointer to the file represented by this handler class.
 167      *
 168      * As a general rule this call should be avoided since if you need to work
 169      * with file objects directly, you are probably better served instantiating
 170      * the File subclasses (i.e. MPEG::File) manually and working with their APIs.
 171      *
 172      * This <i>handle</i> exists to provide a minimal, generic and value-based
 173      * wrapper around a File.  Accessing the file directly generally indicates
 174      * a moving away from this simplicity (and into things beyond the scope of
 175      * FileRef).
 176      *
 177      * \warning This pointer will become invalid when this FileRef and all
 178      * copies pass out of scope.
 179      */
 180     File *file() const;
 181
 182     /*!
 183      * Saves the file.  Returns true on success.
 184      */
 185     bool save();
 186
 187     /*!
 188      * Adds a FileTypeResolver to the list of those used by TagLib.  Each
 189      * additional FileTypeResolver is added to the front of a list of resolvers
 190      * that are tried.  If the FileTypeResolver returns zero the next resolver
 191      * is tried.
 192      *
 193      * Returns a pointer to the added resolver (the same one that's passed in --
 194      * this is mostly so that static inialializers have something to use for
 195      * assignment).
 196      *
 197      * \see FileTypeResolver
 198      */
 199     static const FileTypeResolver *addFileTypeResolver(const FileTypeResolver *resolver);
 200
 201     /*!
 202      * As is mentioned elsewhere in this class's documentation, the default file
 203      * type resolution code provided by TagLib only works by comparing file
 204      * extensions.
 205      *
 206      * This method returns the list of file extensions that are used by default.
 207      *
 208      * The extensions are all returned in lowercase, though the comparison used
 209      * by TagLib for resolution is case-insensitive.
 210      *
 211      * \note This does not account for any additional file type resolvers that
 212      * are plugged in.  Also note that this is not intended to replace a propper
 213      * mime-type resolution system, but is just here for reference.
 214      *
 215      * \see FileTypeResolver
 216      */
 217     static StringList defaultFileExtensions();
 218
 219     /*!
 220      * Returns true if the file (and as such other pointers) are null.
 221      */
 222     bool isNull() const;
 223
 224     /*!
 225      * Assign the file pointed to by \a ref to this FileRef.
 226      */
 227     FileRef &operator=(const FileRef &ref);
 228
 229     /*!
 230      * Returns true if this FileRef and \a ref point to the same File object.
 231      */
 232     bool operator==(const FileRef &ref) const;
 233
 234     /*!
 235      * Returns true if this FileRef and \a ref do not point to the same File
 236      * object.
 237      */
 238     bool operator!=(const FileRef &ref) const;
 239
 240     /*!
 241      * A simple implementation of file type guessing.  If \a readAudioProperties
 242      * is true then the audio properties will be read using
 243      * \a audioPropertiesStyle.  If \a readAudioProperties is false then
 244      * \a audioPropertiesStyle will be ignored.
 245      *
 246      * \note You generally shouldn't use this method, but instead the constructor
 247      * directly.
 248      *
 249      * \deprecated
 250      */
 251     static File *create(FileName fileName,
 252                         bool readAudioProperties = true,
 253                         AudioProperties::ReadStyle audioPropertiesStyle = AudioProperties::Average);
 254
 255
 256   private:
 257     class FileRefPrivate;
 258     FileRefPrivate *d;
 259   };
 260
 261 } // namespace TagLib
 262
 263 #endif