vcs.maemo.org Git - someplayer/blob - src/taglib/toolkit/tfile.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_FILE_H
  27 #define TAGLIB_FILE_H
  28
  29 #include "taglib_export.h"
  30 #include "taglib.h"
  31 #include "tbytevector.h"
  32
  33 namespace TagLib {
  34
  35   class String;
  36   class Tag;
  37   class AudioProperties;
  38
  39 #ifdef _WIN32
  40   class TAGLIB_EXPORT FileName
  41   {
  42   public:
  43     FileName(const wchar_t *name) : m_wname(name) {}
  44     FileName(const char *name) : m_name(name) {}
  45     operator const wchar_t *() const { return m_wname.c_str(); }
  46     operator const char *() const { return m_name.c_str(); }
  47   private:
  48     std::string m_name;
  49     std::wstring m_wname;
  50   };
  51 #else
  52   typedef const char *FileName;
  53 #endif
  54
  55   //! A file class with some useful methods for tag manipulation
  56
  57   /*!
  58    * This class is a basic file class with some methods that are particularly
  59    * useful for tag editors.  It has methods to take advantage of
  60    * ByteVector and a binary search method for finding patterns in a file.
  61    */
  62
  63   class TAGLIB_EXPORT File
  64   {
  65   public:
  66     /*!
  67      * Position in the file used for seeking.
  68      */
  69     enum Position {
  70       //! Seek from the beginning of the file.
  71       Beginning,
  72       //! Seek from the current position in the file.
  73       Current,
  74       //! Seek from the end of the file.
  75       End
  76     };
  77
  78     /*!
  79      * Destroys this File instance.
  80      */
  81     virtual ~File();
  82
  83     /*!
  84      * Returns the file name in the local file system encoding.
  85      */
  86     FileName name() const;
  87
  88     /*!
  89      * Returns a pointer to this file's tag.  This should be reimplemented in
  90      * the concrete subclasses.
  91      */
  92     virtual Tag *tag() const = 0;
  93
  94     /*!
  95      * Returns a pointer to this file's audio properties.  This should be
  96      * reimplemented in the concrete subclasses.  If no audio properties were
  97      * read then this will return a null pointer.
  98      */
  99     virtual AudioProperties *audioProperties() const = 0;
 100
 101     /*!
 102      * Save the file and its associated tags.  This should be reimplemented in
 103      * the concrete subclasses.  Returns true if the save succeeds.
 104      *
 105      * \warning On UNIX multiple processes are able to write to the same file at
 106      * the same time.  This can result in serious file corruption.  If you are
 107      * developing a program that makes use of TagLib from multiple processes you
 108      * must insure that you are only doing writes to a particular file from one
 109      * of them.
 110      */
 111     virtual bool save() = 0;
 112
 113     /*!
 114      * Reads a block of size \a length at the current get pointer.
 115      */
 116     ByteVector readBlock(ulong length);
 117
 118     /*!
 119      * Attempts to write the block \a data at the current get pointer.  If the
 120      * file is currently only opened read only -- i.e. readOnly() returns true --
 121      * this attempts to reopen the file in read/write mode.
 122      *
 123      * \note This should be used instead of using the streaming output operator
 124      * for a ByteVector.  And even this function is significantly slower than
 125      * doing output with a char[].
 126      */
 127     void writeBlock(const ByteVector &data);
 128
 129     /*!
 130      * Returns the offset in the file that \a pattern occurs at or -1 if it can
 131      * not be found.  If \a before is set, the search will only continue until the
 132      * pattern \a before is found.  This is useful for tagging purposes to search
 133      * for a tag before the synch frame.
 134      *
 135      * Searching starts at \a fromOffset, which defaults to the beginning of the
 136      * file.
 137      *
 138      * \note This has the practial limitation that \a pattern can not be longer
 139      * than the buffer size used by readBlock().  Currently this is 1024 bytes.
 140      */
 141     long find(const ByteVector &pattern,
 142               long fromOffset = 0,
 143               const ByteVector &before = ByteVector::null);
 144
 145     /*!
 146      * Returns the offset in the file that \a pattern occurs at or -1 if it can
 147      * not be found.  If \a before is set, the search will only continue until the
 148      * pattern \a before is found.  This is useful for tagging purposes to search
 149      * for a tag before the synch frame.
 150      *
 151      * Searching starts at \a fromOffset and proceeds from the that point to the
 152      * beginning of the file and defaults to the end of the file.
 153      *
 154      * \note This has the practial limitation that \a pattern can not be longer
 155      * than the buffer size used by readBlock().  Currently this is 1024 bytes.
 156      */
 157     long rfind(const ByteVector &pattern,
 158                long fromOffset = 0,
 159                const ByteVector &before = ByteVector::null);
 160
 161     /*!
 162      * Insert \a data at position \a start in the file overwriting \a replace
 163      * bytes of the original content.
 164      *
 165      * \note This method is slow since it requires rewriting all of the file
 166      * after the insertion point.
 167      */
 168     void insert(const ByteVector &data, ulong start = 0, ulong replace = 0);
 169
 170     /*!
 171      * Removes a block of the file starting a \a start and continuing for
 172      * \a length bytes.
 173      *
 174      * \note This method is slow since it involves rewriting all of the file
 175      * after the removed portion.
 176      */
 177     void removeBlock(ulong start = 0, ulong length = 0);
 178
 179     /*!
 180      * Returns true if the file is read only (or if the file can not be opened).
 181      */
 182     bool readOnly() const;
 183
 184     /*!
 185      * Since the file can currently only be opened as an argument to the
 186      * constructor (sort-of by design), this returns if that open succeeded.
 187      */
 188     bool isOpen() const;
 189
 190     /*!
 191      * Returns true if the file is open and readble.
 192      */
 193     bool isValid() const;
 194
 195     /*!
 196      * Move the I/O pointer to \a offset in the file from position \a p.  This
 197      * defaults to seeking from the beginning of the file.
 198      *
 199      * \see Position
 200      */
 201     void seek(long offset, Position p = Beginning);
 202
 203     /*!
 204      * Reset the end-of-file and error flags on the file.
 205      */
 206     void clear();
 207
 208     /*!
 209      * Returns the current offset within the file.
 210      */
 211     long tell() const;
 212
 213     /*!
 214      * Returns the length of the file.
 215      */
 216     long length();
 217
 218     /*!
 219      * Returns true if \a file can be opened for reading.  If the file does not
 220      * exist, this will return false.
 221      *
 222      * \deprecated
 223      */
 224     static bool isReadable(const char *file);
 225
 226     /*!
 227      * Returns true if \a file can be opened for writing.
 228      *
 229      * \deprecated
 230      */
 231     static bool isWritable(const char *name);
 232
 233   protected:
 234     /*!
 235      * Construct a File object and opens the \a file.  \a file should be a
 236      * be a C-string in the local file system encoding.
 237      *
 238      * \note Constructor is protected since this class should only be
 239      * instantiated through subclasses.
 240      */
 241     File(FileName file);
 242
 243     /*!
 244      * Marks the file as valid or invalid.
 245      *
 246      * \see isValid()
 247      */
 248     void setValid(bool valid);
 249
 250     /*!
 251      * Truncates the file to a \a length.
 252      */
 253     void truncate(long length);
 254
 255     /*!
 256      * Returns the buffer size that is used for internal buffering.
 257      */
 258     static uint bufferSize();
 259
 260   private:
 261     File(const File &);
 262     File &operator=(const File &);
 263
 264     class FilePrivate;
 265     FilePrivate *d;
 266   };
 267
 268 }
 269
 270 #endif