1/***************************************************************************
2 copyright : (C) 2011 by Lukas Lalinsky
3 email : lalinsky@gmail.com
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_IOSTREAM_H
27#define TAGLIB_IOSTREAM_H
28
29#include "taglib_export.h"
30#include "taglib.h"
31#include "tbytevector.h"
32
33namespace TagLib {
34
35#ifdef _WIN32
36 class TAGLIB_EXPORT FileName
37 {
38 public:
39 FileName(const wchar_t *name);
40 FileName(const char *name);
41
42 FileName(const FileName &name);
43
44 operator const wchar_t *() const;
45 operator const char *() const;
46
47 const std::wstring &wstr() const;
48 const std::string &str() const;
49
50 String toString() const;
51
52 private:
53 const std::string m_name;
54 const std::wstring m_wname;
55 };
56#else
57 typedef const char *FileName;
58#endif
59
60 //! An abstract class that provides operations on a sequence of bytes
61
62 class TAGLIB_EXPORT IOStream
63 {
64 public:
65 /*!
66 * Position in the file used for seeking.
67 */
68 enum Position {
69 //! Seek from the beginning of the file.
70 Beginning,
71 //! Seek from the current position in the file.
72 Current,
73 //! Seek from the end of the file.
74 End
75 };
76
77 IOStream();
78
79 /*!
80 * Destroys this IOStream instance.
81 */
82 virtual ~IOStream();
83
84 /*!
85 * Returns the stream name in the local file system encoding.
86 */
87 virtual FileName name() const = 0;
88
89 /*!
90 * Reads a block of size \a length at the current get pointer.
91 */
92 virtual ByteVector readBlock(unsigned long length) = 0;
93
94 /*!
95 * Attempts to write the block \a data at the current get pointer. If the
96 * file is currently only opened read only -- i.e. readOnly() returns true --
97 * this attempts to reopen the file in read/write mode.
98 *
99 * \note This should be used instead of using the streaming output operator
100 * for a ByteVector. And even this function is significantly slower than
101 * doing output with a char[].
102 */
103 virtual void writeBlock(const ByteVector &data) = 0;
104
105 /*!
106 * Insert \a data at position \a start in the file overwriting \a replace
107 * bytes of the original content.
108 *
109 * \note This method is slow since it requires rewriting all of the file
110 * after the insertion point.
111 */
112 virtual void insert(const ByteVector &data,
113 unsigned long start = 0, unsigned long replace = 0) = 0;
114
115 /*!
116 * Removes a block of the file starting a \a start and continuing for
117 * \a length bytes.
118 *
119 * \note This method is slow since it involves rewriting all of the file
120 * after the removed portion.
121 */
122 virtual void removeBlock(unsigned long start = 0, unsigned long length = 0) = 0;
123
124 /*!
125 * Returns true if the file is read only (or if the file can not be opened).
126 */
127 virtual bool readOnly() const = 0;
128
129 /*!
130 * Since the file can currently only be opened as an argument to the
131 * constructor (sort-of by design), this returns if that open succeeded.
132 */
133 virtual bool isOpen() const = 0;
134
135 /*!
136 * Move the I/O pointer to \a offset in the stream from position \a p. This
137 * defaults to seeking from the beginning of the stream.
138 *
139 * \see Position
140 */
141 virtual void seek(long offset, Position p = Beginning) = 0;
142
143 /*!
144 * Reset the end-of-stream and error flags on the stream.
145 */
146 virtual void clear();
147
148 /*!
149 * Returns the current offset within the stream.
150 */
151 virtual long tell() const = 0;
152
153 /*!
154 * Returns the length of the stream.
155 */
156 virtual long length() = 0;
157
158 /*!
159 * Truncates the stream to a \a length.
160 */
161 virtual void truncate(long length) = 0;
162
163 private:
164 IOStream(const IOStream &);
165 IOStream &operator=(const IOStream &);
166 };
167
168}
169
170#endif
171