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
34namespace 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 * Destroys this FileStream instance.
59 */
60 virtual ~FileStream();
61
62 /*!
63 * Returns the file name in the local file system encoding.
64 */
65 FileName name() const;
66
67 /*!
68 * Reads a block of size \a length at the current get pointer.
69 */
70 ByteVector readBlock(unsigned long length);
71
72 /*!
73 * Attempts to write the block \a data at the current get pointer. If the
74 * file is currently only opened read only -- i.e. readOnly() returns true --
75 * this attempts to reopen the file in read/write mode.
76 *
77 * \note This should be used instead of using the streaming output operator
78 * for a ByteVector. And even this function is significantly slower than
79 * doing output with a char[].
80 */
81 void writeBlock(const ByteVector &data);
82
83 /*!
84 * Insert \a data at position \a start in the file overwriting \a replace
85 * bytes of the original content.
86 *
87 * \note This method is slow since it requires rewriting all of the file
88 * after the insertion point.
89 */
90 void insert(const ByteVector &data, unsigned long start = 0, unsigned long replace = 0);
91
92 /*!
93 * Removes a block of the file starting a \a start and continuing for
94 * \a length bytes.
95 *
96 * \note This method is slow since it involves rewriting all of the file
97 * after the removed portion.
98 */
99 void removeBlock(unsigned long start = 0, unsigned long length = 0);
100
101 /*!
102 * Returns true if the file is read only (or if the file can not be opened).
103 */
104 bool readOnly() const;
105
106 /*!
107 * Since the file can currently only be opened as an argument to the
108 * constructor (sort-of by design), this returns if that open succeeded.
109 */
110 bool isOpen() const;
111
112 /*!
113 * Move the I/O pointer to \a offset in the file from position \a p. This
114 * defaults to seeking from the beginning of the file.
115 *
116 * \see Position
117 */
118 void seek(long offset, Position p = Beginning);
119
120 /*!
121 * Reset the end-of-file and error flags on the file.
122 */
123 void clear();
124
125 /*!
126 * Returns the current offset within the file.
127 */
128 long tell() const;
129
130 /*!
131 * Returns the length of the file.
132 */
133 long length();
134
135 /*!
136 * Truncates the file to a \a length.
137 */
138 void truncate(long length);
139
140 protected:
141
142 /*!
143 * Returns the buffer size that is used for internal buffering.
144 */
145 static unsigned int bufferSize();
146
147 private:
148 class FileStreamPrivate;
149 FileStreamPrivate *d;
150 };
151
152}
153
154#endif
155