Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: datstrm.h | |
f09b5681 | 3 | // Purpose: interface of wxDataInputStream and wxDataOutputStream |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxDataOutputStream | |
7c913512 | 11 | |
f09b5681 BP |
12 | This class provides functions that write binary data types in a portable |
13 | way. Data can be written in either big-endian or little-endian format, | |
14 | little-endian being the default on all architectures. | |
7c913512 | 15 | |
f09b5681 BP |
16 | If you want to write data to text files (or streams) use wxTextOutputStream |
17 | instead. | |
7c913512 | 18 | |
f09b5681 BP |
19 | The "<<" operator is overloaded and you can use this class like a standard |
20 | C++ iostream. See wxDataInputStream for its usage and caveats. | |
7c913512 | 21 | |
23324ae1 FM |
22 | @library{wxbase} |
23 | @category{streams} | |
f09b5681 BP |
24 | |
25 | @see wxDataInputStream | |
23324ae1 | 26 | */ |
7c913512 | 27 | class wxDataOutputStream |
23324ae1 FM |
28 | { |
29 | public: | |
23324ae1 | 30 | /** |
76e9224e FM |
31 | Constructs a datastream object from an output stream. |
32 | Only write methods will be available. | |
3c4f71cc | 33 | |
7323ff1a | 34 | Note that the @a conv parameter is only available in Unicode builds of wxWidgets. |
f09b5681 BP |
35 | |
36 | @param stream | |
37 | The output stream. | |
38 | @param conv | |
39 | Charset conversion object object used to encoding Unicode strings | |
40 | before writing them to the stream in Unicode mode (see | |
41 | WriteString() for a detailed description). Note that you must not | |
42 | destroy @a conv before you destroy this wxDataOutputStream | |
43 | instance! It is recommended to use the default value (UTF-8). | |
44 | */ | |
45 | wxDataOutputStream(wxOutputStream& stream, | |
107ea8f0 | 46 | const wxMBConv& conv = wxConvUTF8); |
23324ae1 FM |
47 | |
48 | /** | |
49 | Destroys the wxDataOutputStream object. | |
50 | */ | |
51 | ~wxDataOutputStream(); | |
52 | ||
53 | /** | |
f09b5681 BP |
54 | If @a be_order is @true, all data will be written in big-endian order, |
55 | e.g. for reading on a Sparc or from Java-Streams (which always use | |
56 | big-endian order), otherwise data will be written in little-endian | |
57 | order. | |
23324ae1 FM |
58 | */ |
59 | void BigEndianOrdered(bool be_order); | |
10c2f98a RR |
60 | |
61 | /** | |
62 | Returns the current text conversion class used for | |
63 | writing strings. | |
64 | */ | |
65 | wxMBConv *GetConv() const; | |
23324ae1 | 66 | |
10c2f98a RR |
67 | /** |
68 | Sets the text conversion class used for writing strings. | |
69 | */ | |
70 | void SetConv( const wxMBConv &conv ); | |
71 | ||
f09b5681 BP |
72 | /** |
73 | Writes the single byte @a i8 to the stream. | |
74 | */ | |
75 | void Write8(wxUint8 i8); | |
76 | /** | |
77 | Writes an array of bytes to the stream. The amount of bytes to write is | |
78 | specified with the @a size variable. | |
79 | */ | |
80 | void Write8(const wxUint8* buffer, size_t size); | |
81 | ||
82 | /** | |
83 | Writes the 16 bit unsigned integer @a i16 to the stream. | |
84 | */ | |
85 | void Write16(wxUint16 i16); | |
23324ae1 FM |
86 | /** |
87 | Writes an array of 16 bit unsigned integer to the stream. The amount of | |
4cc4bfaf | 88 | 16 bit unsigned integer to write is specified with the @a size variable. |
23324ae1 | 89 | */ |
4cc4bfaf | 90 | void Write16(const wxUint16* buffer, size_t size); |
23324ae1 | 91 | |
f09b5681 BP |
92 | /** |
93 | Writes the 32 bit unsigned integer @a i32 to the stream. | |
94 | */ | |
95 | void Write32(wxUint32 i32); | |
23324ae1 FM |
96 | /** |
97 | Writes an array of 32 bit unsigned integer to the stream. The amount of | |
4cc4bfaf | 98 | 32 bit unsigned integer to write is specified with the @a size variable. |
23324ae1 | 99 | */ |
4cc4bfaf | 100 | void Write32(const wxUint32* buffer, size_t size); |
23324ae1 | 101 | |
f09b5681 BP |
102 | /** |
103 | Writes the 64 bit unsigned integer @a i64 to the stream. | |
104 | */ | |
105 | void Write64(wxUint64 i64); | |
23324ae1 FM |
106 | /** |
107 | Writes an array of 64 bit unsigned integer to the stream. The amount of | |
4cc4bfaf | 108 | 64 bit unsigned integer to write is specified with the @a size variable. |
23324ae1 | 109 | */ |
4cc4bfaf | 110 | void Write64(const wxUint64* buffer, size_t size); |
23324ae1 | 111 | |
23324ae1 | 112 | /** |
f09b5681 | 113 | Writes the double @a f to the stream using the IEEE format. |
23324ae1 | 114 | */ |
f09b5681 | 115 | void WriteDouble(double f); |
23324ae1 FM |
116 | /** |
117 | Writes an array of double to the stream. The amount of double to write is | |
4cc4bfaf | 118 | specified with the @a size variable. |
23324ae1 | 119 | */ |
4cc4bfaf | 120 | void WriteDouble(const double* buffer, size_t size); |
23324ae1 FM |
121 | |
122 | /** | |
f09b5681 BP |
123 | Writes @a string to the stream. Actually, this method writes the size |
124 | of the string before writing @a string itself. | |
125 | ||
126 | In ANSI build of wxWidgets, the string is written to the stream in | |
127 | exactly same way it is represented in memory. In Unicode build, | |
128 | however, the string is first converted to multibyte representation with | |
129 | @e conv object passed to stream's constructor (consequently, ANSI | |
130 | applications can read data written by Unicode application, as long as | |
131 | they agree on encoding) and this representation is written to the | |
132 | stream. UTF-8 is used by default. | |
23324ae1 FM |
133 | */ |
134 | void WriteString(const wxString& string); | |
135 | }; | |
136 | ||
137 | ||
e54c96f1 | 138 | |
23324ae1 FM |
139 | /** |
140 | @class wxDataInputStream | |
7c913512 | 141 | |
f09b5681 BP |
142 | This class provides functions that read binary data types in a portable |
143 | way. Data can be read in either big-endian or little-endian format, | |
144 | little-endian being the default on all architectures. | |
7c913512 | 145 | |
f09b5681 BP |
146 | If you want to read data from text files (or streams) use wxTextInputStream |
147 | instead. | |
7c913512 | 148 | |
f09b5681 BP |
149 | The ">>" operator is overloaded and you can use this class like a standard |
150 | C++ iostream. Note, however, that the arguments are the fixed size types | |
151 | wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match | |
152 | to the "long" type (wxInt32 is defined as signed int on 32-bit | |
153 | architectures) so that you cannot use long. To avoid problems (here and | |
154 | elsewhere), make use of the wxInt32, wxUint32, etc types. | |
7c913512 | 155 | |
23324ae1 | 156 | For example: |
7c913512 | 157 | |
23324ae1 FM |
158 | @code |
159 | wxFileInputStream input( "mytext.dat" ); | |
f09b5681 BP |
160 | wxDataInputStream store( input ); |
161 | wxUint8 i1; | |
162 | float f2; | |
163 | wxString line; | |
164 | ||
165 | store >> i1; // read a 8 bit integer. | |
166 | store >> i1 >> f2; // read a 8 bit integer followed by float. | |
167 | store >> line; // read a text line | |
23324ae1 | 168 | @endcode |
7c913512 | 169 | |
23324ae1 FM |
170 | @library{wxbase} |
171 | @category{streams} | |
f09b5681 BP |
172 | |
173 | @see wxDataOutputStream | |
23324ae1 | 174 | */ |
7c913512 | 175 | class wxDataInputStream |
23324ae1 FM |
176 | { |
177 | public: | |
23324ae1 | 178 | /** |
76e9224e FM |
179 | Constructs a datastream object from an input stream. |
180 | Only read methods will be available. | |
f09b5681 | 181 | |
7323ff1a | 182 | Note that the @a conv parameter is only available in Unicode builds of wxWidgets. |
3c4f71cc | 183 | |
7c913512 | 184 | @param stream |
4cc4bfaf | 185 | The input stream. |
7c913512 | 186 | @param conv |
4cc4bfaf | 187 | Charset conversion object object used to decode strings in Unicode |
f09b5681 BP |
188 | mode (see ReadString() for a detailed description). Note that you |
189 | must not destroy @a conv before you destroy this wxDataInputStream | |
190 | instance! | |
23324ae1 | 191 | */ |
f09b5681 | 192 | wxDataInputStream(wxInputStream& stream, |
107ea8f0 | 193 | const wxMBConv& conv = wxConvUTF8 ); |
23324ae1 FM |
194 | |
195 | /** | |
196 | Destroys the wxDataInputStream object. | |
197 | */ | |
198 | ~wxDataInputStream(); | |
199 | ||
200 | /** | |
f09b5681 BP |
201 | If @a be_order is @true, all data will be read in big-endian order, |
202 | such as written by programs on a big endian architecture (e.g. Sparc) | |
203 | or written by Java-Streams (which always use big-endian order). | |
23324ae1 FM |
204 | */ |
205 | void BigEndianOrdered(bool be_order); | |
206 | ||
10c2f98a RR |
207 | |
208 | /** | |
209 | Returns the current text conversion class used for | |
210 | reading strings. | |
211 | */ | |
212 | wxMBConv *GetConv() const; | |
213 | ||
23324ae1 | 214 | /** |
f09b5681 BP |
215 | Reads a single byte from the stream. |
216 | */ | |
217 | wxUint8 Read8(); | |
218 | /** | |
219 | Reads bytes from the stream in a specified buffer. The amount of bytes | |
220 | to read is specified by the @a size variable. | |
221 | */ | |
222 | void Read8(wxUint8* buffer, size_t size); | |
223 | ||
224 | /** | |
225 | Reads a 16 bit unsigned integer from the stream. | |
23324ae1 FM |
226 | */ |
227 | wxUint16 Read16(); | |
f09b5681 BP |
228 | /** |
229 | Reads 16 bit unsigned integers from the stream in a specified buffer. | |
230 | The amount of 16 bit unsigned integers to read is specified by the | |
231 | @a size variable. | |
232 | */ | |
4cc4bfaf | 233 | void Read16(wxUint16* buffer, size_t size); |
23324ae1 | 234 | |
23324ae1 | 235 | /** |
f09b5681 | 236 | Reads a 32 bit unsigned integer from the stream. |
23324ae1 FM |
237 | */ |
238 | wxUint32 Read32(); | |
f09b5681 BP |
239 | /** |
240 | Reads 32 bit unsigned integers from the stream in a specified buffer. | |
241 | The amount of 32 bit unsigned integers to read is specified by the | |
242 | @a size variable. | |
243 | */ | |
4cc4bfaf | 244 | void Read32(wxUint32* buffer, size_t size); |
23324ae1 | 245 | |
23324ae1 | 246 | /** |
f09b5681 | 247 | Reads a 64 bit unsigned integer from the stream. |
23324ae1 FM |
248 | */ |
249 | wxUint64 Read64(); | |
23324ae1 | 250 | /** |
f09b5681 BP |
251 | Reads 64 bit unsigned integers from the stream in a specified buffer. |
252 | The amount of 64 bit unsigned integers to read is specified by the | |
253 | @a size variable. | |
23324ae1 | 254 | */ |
f09b5681 | 255 | void Read64(wxUint64* buffer, size_t size); |
23324ae1 | 256 | |
23324ae1 | 257 | /** |
f09b5681 | 258 | Reads a double (IEEE encoded) from the stream. |
23324ae1 FM |
259 | */ |
260 | double ReadDouble(); | |
f09b5681 BP |
261 | /** |
262 | Reads double data (IEEE encoded) from the stream in a specified buffer. | |
263 | The amount of doubles to read is specified by the @a size variable. | |
264 | */ | |
4cc4bfaf | 265 | void ReadDouble(double* buffer, size_t size); |
23324ae1 FM |
266 | |
267 | /** | |
f09b5681 BP |
268 | Reads a string from a stream. Actually, this function first reads a |
269 | long integer specifying the length of the string (without the last null | |
270 | character) and then reads the string. | |
271 | ||
272 | In Unicode build of wxWidgets, the fuction first reads multibyte | |
273 | (char*) string from the stream and then converts it to Unicode using | |
274 | the @e conv object passed to constructor and returns the result as | |
275 | wxString. You are responsible for using the same convertor as when | |
276 | writing the stream. | |
277 | ||
278 | @see wxDataOutputStream::WriteString() | |
23324ae1 FM |
279 | */ |
280 | wxString ReadString(); | |
10c2f98a RR |
281 | |
282 | /** | |
283 | Sets the text conversion class used for reading strings. | |
284 | */ | |
285 | void SetConv( const wxMBConv &conv ); | |
23324ae1 | 286 | }; |
e54c96f1 | 287 |