Remove do-nothing command and add warning about it
[amule.git] / src / SafeFile.h
blob723900b5c27ddedbd80c45079a41ef0a040a1e50
1 //
2 // This file is part of the aMule Project.
3 //
4 // Copyright (c) 2003-2011 aMule Team ( admin@amule.org / http://www.amule.org )
5 // Copyright (c) 2002-2011 Merkur ( devs@emule-project.net / http://www.emule-project.net )
6 //
7 // Any parts of this program derived from the xMule, lMule or eMule project,
8 // or contributed by third-party developers are copyrighted by their
9 // respective authors.
11 // This program is free software; you can redistribute it and/or modify
12 // it under the terms of the GNU General Public License as published by
13 // the Free Software Foundation; either version 2 of the License, or
14 // (at your option) any later version.
16 // This program is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 // GNU General Public License for more details.
21 // You should have received a copy of the GNU General Public License
22 // along with this program; if not, write to the Free Software
23 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
26 #ifndef SAFEFILE_H
27 #define SAFEFILE_H
30 #include <wx/filename.h> // Needed for wxFileName
31 #include <common/MuleDebug.h> // Needef for CMuleException
32 #include "Tag.h"
34 namespace Kademlia {
35 class CUInt128;
37 using Kademlia::CUInt128;
38 class CMD4Hash;
41 /**
42 * This class provides a interface for safe file IO.
44 * Basic IO operations will either succeed or throw an exception,
45 * so that failure cannot be ignored. There are currently 3 types
46 * of failures: Read past EOF, errors while reading, and errors
47 * while writing.
49 * Beyond basic IO, the interface provides functions for reading
50 * and writing a number of simple data-types. These are all written
51 * and read as little-endian in order to allow for communication
52 * across platforms.
54 * Note that when empty areas are created, for instance by seeking
55 * past the end, then writing, the value of bytes where no data was
56 * explicitly written is not specified.
58 class CFileDataIO
60 public:
61 /**
62 * The Destructor does nothing, but is needed to allow
63 * for safe deletion objects via CFileDataIO pointers.
65 virtual ~CFileDataIO();
68 /**
69 * Must return the current position in the file.
71 virtual uint64 GetPosition() const = 0;
73 /**
74 * Must return the length of the file-object in bytes.
76 virtual uint64 GetLength() const = 0;
78 /**
79 * Returns true when the file-position is past or at the end of the file.
81 virtual bool Eof() const;
84 /**
85 * Changes the file position.
87 * Note that seeking to an negative position is an illegal operation.
89 * @see wxFile::Seek
91 virtual uint64 Seek(sint64 offset, wxSeekMode from = wxFromStart) const;
94 /**
95 * Reads 'count' bytes into 'buffer'.
97 * @param buffer The target buffer.
98 * @param count The number of bytes to read.
100 * Note that Read will read the specified number of
101 * bytes unless this would read past the end of the
102 * file. In that case, a CEOFException is thrown and
103 * the position and target buffer is left unchanged.
105 * However, it is also possible that the read will
106 * fail due to IO errors (bad hardware, ect), in which
107 * case an CIOFailureException will be thrown.
109 virtual void Read(void* buffer, size_t count) const;
112 * Write 'count' bytes from 'buffer' into the file.
114 * @param buffer The source-data buffer.
115 * @param count The number of bytes to write.
117 * Note that Write will throw a CIOFailureException
118 * if it fails to write the specified number of bytes,
119 * which can be caused by hardware failures, lack of
120 * free space, etc.
122 virtual void Write(const void* buffer, size_t count);
126 * Reads the given type from the file, stored as little-endian.
128 * @see CSafeFileIO::Read
130 //@{
131 virtual uint8 ReadUInt8() const;
132 virtual uint16 ReadUInt16() const;
133 virtual uint32 ReadUInt32() const;
134 virtual uint64 ReadUInt64() const;
135 virtual CUInt128 ReadUInt128() const;
136 virtual CMD4Hash ReadHash() const;
137 virtual float ReadFloat() const;
138 virtual unsigned char* ReadBsob(uint8* size) const;
139 //@}
142 * Reads a string from the file.
144 * @param bOptUTF8 Specifies if the string is UTF8 encoded.
145 * @param lenBytes The number of bytes used to store the string length.
146 * @param SafeRead Avoids throwing CEOFException, see below.
147 * @return The resulting text-string.
149 * Note that when SafeRead is set to true, CSafeFileIO will crop the length
150 * read from the lenght-field (see lenBytes), so that at most GetLength() -
151 * GetPosition() bytes are read.
153 * @see CSafeFileIO::Read
155 virtual wxString ReadString(bool bOptUTF8, uint8 lenBytes = 2, bool SafeRead = false) const;
158 * Reads a string from the file, where the length is specified directly.
160 * @param bOptUTF8 Specifies if the string is UTF8 encoded.
161 * @param length The length of the string.
162 * @return The resulting text-string.
164 * This function is typically used when the text-fields length is not stored
165 * as an integer-field in front of the text-field.
167 virtual wxString ReadOnlyString(bool bOptUTF8, uint16 length) const;
171 * Writes a value of the given type to the file, storing it as little-endian.
173 * @see CSafeFileIO::Write
175 //@{
176 virtual void WriteUInt8(uint8 value);
177 virtual void WriteUInt16(uint16 value);
178 virtual void WriteUInt32(uint32 value);
179 virtual void WriteUInt64(uint64 value);
180 virtual void WriteUInt128(const CUInt128& value);
181 virtual void WriteHash(const CMD4Hash& value);
182 virtual void WriteFloat(float value);
183 virtual void WriteBsob( const unsigned char* val, uint8 size);
184 //@}
187 * Writes a text-string to the file.
189 * @param str The string to be written.
190 * @param encoding The text-ecoding, see EUtf8Str.
191 * @param lenBytes The number of bytes used to store the string length.
193 * Valid values for the 'lenBytes' parameters is 0 bytes (no length field),
194 * 2 bytes and 4 bytes.
196 * @see CSafeFileIO::Write
198 virtual void WriteString(const wxString& str, EUtf8Str encoding = utf8strNone, uint8 lenBytes = 2);
200 /* Warning: Special Kad functions, needs documentation */
202 CTag* ReadTag(bool bOptACP = false) const;
203 void ReadTagPtrList(TagPtrList* taglist, bool bOptACP = false) const;
205 void WriteTag(const CTag& tag);
206 void WriteTagPtrList(const TagPtrList& tagList);
208 /* Special ED2Kv2 function */
209 uint64 GetIntTagValue() const;
211 /* Some functions I added for simplicity */
212 // Very obvious
213 bool IsEmpty() { return (GetLength() == 0); }
215 // Appends to the end
216 void Append(const uint8* buffer, int n) { Seek(0, wxFromEnd); Write(buffer, n); }
218 protected:
220 * The actual read / write function, as implemented by subclasses.
222 * @param buffer The buffer to read data into / write data from.
223 * @param count The number of bytes to read / written.
224 * @return The number of bytes read / written or -1 in case of errors.
226 * Note that the return value must be the actual number of bytes
227 * read or written, with the exception that in case of errors, -1
228 * may be returned. This is because the return value is used to
229 * detect if the operation succeded.
231 * This function should not throw Either of the CSafeIOExceptions,
232 * this is done by the CSafeFileIO::Read and the CSafeFileIO::Write
233 * functions.
235 //@{
236 virtual sint64 doRead(void* buffer, size_t count) const = 0;
237 virtual sint64 doWrite(const void* buffer, size_t count) = 0;
238 //@}
241 * The actual seek function, as implemented by subclasses.
243 * @param offset The absolute offset to seek to.
244 * @return The resulting offset.
246 * This function should not throw of the CSafeIOExceptions,
247 * this is handled by the CSafeFileIO::Seek. At the moment,
248 * seeks that fail are considered a fatal error.
250 virtual sint64 doSeek(sint64 offset) const = 0;
252 private:
254 * Helper-function that does the actual writing of the string.
256 * @param str The string to be written.
257 * @param encoding The encoding of the string.
258 * @param lenBytes The number of bytes used to store the string length.
261 void WriteStringCore(const char* str, EUtf8Str encoding, uint8 lenBytes);
266 * The base class of IO exceptions used by
267 * the CSafeFileIO interface and implementations
268 * of the interface.
270 struct CSafeIOException : public CMuleException
272 CSafeIOException(const wxString& type, const wxString& desc);
277 * This exception is thrown when attempts are
278 * made at reading past the end of the file.
280 * This typically happens when a invalid packet
281 * is received that is shorter than expected and
282 * is not fatal.
284 struct CEOFException : public CSafeIOException {
285 CEOFException(const wxString& desc);
290 * This exception reflects a failure in performing
291 * basic IO operations read and write. It will be
292 * thrown in case a read or a write fails to read
293 * or write the specified number of bytes.
295 struct CIOFailureException : public CSafeIOException {
296 CIOFailureException(const wxString& type, const wxString& desc);
297 CIOFailureException(const wxString& desc);
301 #endif // SAFEFILE_H
302 // File_checked_for_headers