Pyrogenesis  trunk
FileIo.h
Go to the documentation of this file.
1 /* Copyright (C) 2009 Wildfire Games.
2  * This file is part of 0 A.D.
3  *
4  * 0 A.D. is free software: you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation, either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * 0 A.D. is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with 0 A.D. If not, see <http://www.gnu.org/licenses/>.
16  */
17 
18 /*
19  * endian-safe binary file IO helpers.
20  */
21 
22 // the file format has passing similarity to IFF. note however that
23 // "chunks" aren't identified by FOURCCs; only the file header is
24 // so marked.
25 // all > 8-bit integers are stored in little-endian format
26 // (hence the _le suffix). however, the caller is responsible for
27 // swapping their raw data before passing it to PackRaw. a convenience
28 // routine is provided for the common case of storing size_t.
29 
30 #ifndef INCLUDED_FILEPACKER
31 #define INCLUDED_FILEPACKER
32 
33 #include "CStr.h"
34 #include "lib/file/vfs/vfs_path.h"
35 #include "ps/Filesystem.h" // WriteBuffer
36 
37 #include "ps/Errors.h"
39 ERROR_TYPE(File, OpenFailed);
40 ERROR_TYPE(File, WriteFailed);
41 ERROR_TYPE(File, InvalidType);
42 ERROR_TYPE(File, InvalidVersion);
43 ERROR_TYPE(File, ReadFailed);
44 ERROR_TYPE(File, UnexpectedEOF);
45 
46 
47 /**
48  * helper class for writing binary files. this is basically a
49  * resizable buffer that allows adding raw data and strings;
50  * upon calling Write(), everything is written out to disk.
51  **/
53 {
54 public:
55  /**
56  * adds version and signature (i.e. the header) to the buffer.
57  * this means Write() can write the entire buffer to file in one go,
58  * which is simpler and more efficient than writing in pieces.
59  **/
60  CFilePacker(u32 version, const char magic[4]);
61 
62  ~CFilePacker();
63 
64  /**
65  * write out to file all packed data added so far.
66  * it's safe to call this multiple times, but typically would
67  * only be done once.
68  **/
69  void Write(const VfsPath& filename);
70 
71  /**
72  * pack given number of bytes onto the end of the data stream
73  **/
74  void PackRaw(const void* rawData, size_t rawDataSize);
75 
76  /**
77  * convenience: convert a number (almost always a size type) to
78  * little-endian u32 and pack that.
79  **/
80  void PackSize(size_t value);
81 
82  /**
83  * pack a string onto the end of the data stream
84  * (encoded as a 32-bit length followed by the characters)
85  **/
86  void PackString(const CStr& str);
87 
88 private:
89  /**
90  * the output data stream built during pack operations.
91  * contains the header, so we can write this out in one go.
92  **/
94 };
95 
96 
97 /**
98  * helper class for reading binary files
99  **/
101 {
102 public:
103  CFileUnpacker();
104  ~CFileUnpacker();
105 
106  /**
107  * open and read in given file, check magic bits against those given;
108  * throw variety of exceptions if open failed / version incorrect, etc.
109  **/
110  void Read(const VfsPath& filename, const char magic[4]);
111 
112  /**
113  * @return version number that was stored in the file's header.
114  **/
115  u32 GetVersion() const
116  {
117  return m_version;
118  }
119 
120  /**
121  * unpack given number of bytes from the input into the given array.
122  * throws PSERROR_File_UnexpectedEOF if the end of the data stream is
123  * reached before the given number of bytes have been read.
124  **/
125  void UnpackRaw(void* rawData, size_t rawDataSize);
126 
127  /**
128  * use UnpackRaw to retrieve 32-bits; returns their value as size_t
129  * after converting from little endian to native byte order.
130  **/
131  size_t UnpackSize();
132 
133  /**
134  * unpack a string from the raw data stream.
135  * @param result is assigned a newly constructed CStr8 holding the
136  * string read from the input stream.
137  **/
138  void UnpackString(CStr8& result);
139 
140 private:
141  // the data read from file and used during unpack operations
142  shared_ptr<u8> m_buf;
143  size_t m_bufSize;
144 
145  size_t m_unpackPos; /// current unpack position in stream
146  u32 m_version; /// version that was stored in the file header
147 };
148 
149 #endif
ERROR_GROUP(File)
void PackRaw(const void *rawData, size_t rawDataSize)
pack given number of bytes onto the end of the data stream
Definition: FileIo.cpp:78
WriteBuffer m_writeBuffer
the output data stream built during pack operations.
Definition: FileIo.h:93
helper class for reading binary files
Definition: FileIo.h:100
u32 GetVersion() const
Definition: FileIo.h:115
helper class for writing binary files.
Definition: FileIo.h:52
uint32_t u32
Definition: types.h:39
Definition: path.h:77
CFilePacker(u32 version, const char magic[4])
adds version and signature (i.e.
Definition: FileIo.cpp:45
size_t m_bufSize
Definition: FileIo.h:143
~CFilePacker()
Definition: FileIo.cpp:57
u64 Read(u64 reg)
Definition: msr.cpp:130
void Write(const VfsPath &filename)
write out to file all packed data added so far.
Definition: FileIo.cpp:62
u32 m_version
current unpack position in stream
Definition: FileIo.h:146
void PackSize(size_t value)
convenience: convert a number (almost always a size type) to little-endian u32 and pack that...
Definition: FileIo.cpp:83
Definition: write_buffer.h:28
Definition: file.h:45
void PackString(const CStr &str)
pack a string onto the end of the data stream (encoded as a 32-bit length followed by the characters)...
Definition: FileIo.cpp:89
ERROR_TYPE(File, OpenFailed)
shared_ptr< u8 > m_buf
Definition: FileIo.h:142
size_t m_unpackPos
Definition: FileIo.h:145