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 
33 namespace 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