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., 51 Franklin Street, Fifth Floor, Boston, MA         *
19  *   02110-1301  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_FILESTREAM_H
27 #define TAGLIB_FILESTREAM_H
28 
29 #include "taglib_export.h"
30 #include "taglib.h"
31 #include "tbytevector.h"
32 #include "tiostream.h"
33 
34 namespace TagLib {
35 
36   class String;
37   class Tag;
38   class AudioProperties;
39 
40   //! A file class with some useful methods for tag manipulation
41 
42   /*!
43    * This class is a basic file class with some methods that are particularly
44    * useful for tag editors.  It has methods to take advantage of
45    * ByteVector and a binary search method for finding patterns in a file.
46    */
47 
48   class TAGLIB_EXPORT FileStream : public IOStream
49   {
50   public:
51     /*!
52      * Construct a File object and opens the \a file.  \a file should be a
53      * be a C-string in the local file system encoding.
54      */
55     FileStream(FileName file, bool openReadOnly = false);
56 
57     /*!
58      * Construct a File object and opens the \a file using file descriptor.
59      */
60     FileStream(int fileDescriptor, bool openReadOnly = false);
61 
62     /*!
63      * Destroys this FileStream instance.
64      */
65     virtual ~FileStream();
66 
67     /*!
68      * Returns the file name in the local file system encoding.
69      */
70     FileName name() const;
71 
72     /*!
73      * Reads a block of size \a length at the current get pointer.
74      */
75     ByteVector readBlock(unsigned long length);
76 
77     /*!
78      * Attempts to write the block \a data at the current get pointer.  If the
79      * file is currently only opened read only -- i.e. readOnly() returns true --
80      * this attempts to reopen the file in read/write mode.
81      *
82      * \note This should be used instead of using the streaming output operator
83      * for a ByteVector.  And even this function is significantly slower than
84      * doing output with a char[].
85      */
86     void writeBlock(const ByteVector &data);
87 
88     /*!
89      * Insert \a data at position \a start in the file overwriting \a replace
90      * bytes of the original content.
91      *
92      * \note This method is slow since it requires rewriting all of the file
93      * after the insertion point.
94      */
95     void insert(const ByteVector &data, unsigned long start = 0, unsigned long replace = 0);
96 
97     /*!
98      * Removes a block of the file starting a \a start and continuing for
99      * \a length bytes.
100      *
101      * \note This method is slow since it involves rewriting all of the file
102      * after the removed portion.
103      */
104     void removeBlock(unsigned long start = 0, unsigned long length = 0);
105 
106     /*!
107      * Returns true if the file is read only (or if the file can not be opened).
108      */
109     bool readOnly() const;
110 
111     /*!
112      * Since the file can currently only be opened as an argument to the
113      * constructor (sort-of by design), this returns if that open succeeded.
114      */
115     bool isOpen() const;
116 
117     /*!
118      * Move the I/O pointer to \a offset in the file from position \a p.  This
119      * defaults to seeking from the beginning of the file.
120      *
121      * \see Position
122      */
123     void seek(long offset, Position p = Beginning);
124 
125     /*!
126      * Reset the end-of-file and error flags on the file.
127      */
128     void clear();
129 
130     /*!
131      * Returns the current offset within the file.
132      */
133     long tell() const;
134 
135     /*!
136      * Returns the length of the file.
137      */
138     long length();
139 
140     /*!
141      * Truncates the file to a \a length.
142      */
143     void truncate(long length);
144 
145   protected:
146 
147     /*!
148      * Returns the buffer size that is used for internal buffering.
149      */
150     static unsigned int bufferSize();
151 
152   private:
153     class FileStreamPrivate;
154     FileStreamPrivate *d;
155   };
156 
157 }
158 
159 #endif
160