]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: stream.h | |
3 | // Purpose: interface of wxStreamBase and its derived classes | |
4 | // Author: wxWidgets team | |
5 | // Licence: wxWindows licence | |
6 | ///////////////////////////////////////////////////////////////////////////// | |
7 | ||
8 | ||
9 | /** | |
10 | These enumeration values are returned by various functions in the context | |
11 | of wxStream classes. | |
12 | */ | |
13 | enum wxStreamError | |
14 | { | |
15 | wxSTREAM_NO_ERROR = 0, //!< No error occurred. | |
16 | wxSTREAM_EOF, //!< EOF reached in Read() or similar. | |
17 | wxSTREAM_WRITE_ERROR, //!< generic write error on the last write call. | |
18 | wxSTREAM_READ_ERROR //!< generic read error on the last read call. | |
19 | }; | |
20 | ||
21 | /** | |
22 | @class wxStreamBase | |
23 | ||
24 | This class is the base class of most stream related classes in wxWidgets. | |
25 | It must not be used directly. | |
26 | ||
27 | @library{wxbase} | |
28 | @category{streams} | |
29 | ||
30 | @see wxStreamBuffer | |
31 | */ | |
32 | class wxStreamBase | |
33 | { | |
34 | public: | |
35 | /** | |
36 | Creates a dummy stream object. It doesn't do anything. | |
37 | */ | |
38 | wxStreamBase(); | |
39 | ||
40 | /** | |
41 | Destructor. | |
42 | */ | |
43 | virtual ~wxStreamBase(); | |
44 | ||
45 | /** | |
46 | This function returns the last error. | |
47 | */ | |
48 | wxStreamError GetLastError() const; | |
49 | ||
50 | /** | |
51 | Returns the length of the stream in bytes. If the length cannot be | |
52 | determined (this is always the case for socket streams for example), | |
53 | returns ::wxInvalidOffset. | |
54 | ||
55 | @since 2.5.4 | |
56 | */ | |
57 | virtual wxFileOffset GetLength() const; | |
58 | ||
59 | /** | |
60 | This function returns the size of the stream. | |
61 | For example, for a file it is the size of the file. | |
62 | ||
63 | @warning | |
64 | There are streams which do not have size by definition, such as socket | |
65 | streams. In that cases, GetSize() returns 0 so you should always test its | |
66 | return value. | |
67 | */ | |
68 | virtual size_t GetSize() const; | |
69 | ||
70 | /** | |
71 | Returns @true if no error occurred on the stream. | |
72 | ||
73 | @see GetLastError() | |
74 | */ | |
75 | virtual bool IsOk() const; | |
76 | ||
77 | /** | |
78 | Returns @true if the stream supports seeking to arbitrary offsets. | |
79 | */ | |
80 | virtual bool IsSeekable() const; | |
81 | ||
82 | /** | |
83 | Resets the stream state. | |
84 | ||
85 | By default, resets the stream to good state, i.e. clears any errors. | |
86 | Since wxWidgets 2.9.3 can be also used to explicitly set the state to | |
87 | the specified error (the @a error argument didn't exist in the previous | |
88 | versions). | |
89 | ||
90 | @see GetLastError() | |
91 | */ | |
92 | void Reset(wxStreamError error = wxSTREAM_NO_ERROR); | |
93 | ||
94 | /** | |
95 | Returns the opposite of IsOk(). | |
96 | You can use this function to test the validity of the stream as if | |
97 | it was a pointer: | |
98 | ||
99 | @code | |
100 | bool DoSomething(wxInputStream& stream) | |
101 | { | |
102 | wxInt32 data; | |
103 | if (!stream.Read(&data, 4)) | |
104 | return false; | |
105 | ... | |
106 | } | |
107 | @endcode | |
108 | */ | |
109 | bool operator!() const; | |
110 | ||
111 | protected: | |
112 | ||
113 | /** | |
114 | Internal function. | |
115 | It is called when the stream needs to change the current position. | |
116 | ||
117 | @param pos | |
118 | Offset to seek to. | |
119 | @param mode | |
120 | One of the ::wxSeekMode enumeration values. | |
121 | ||
122 | @return The new stream position or ::wxInvalidOffset on error. | |
123 | */ | |
124 | virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode); | |
125 | ||
126 | /** | |
127 | Internal function. | |
128 | It is called when the stream needs to know the real position. | |
129 | ||
130 | @return The current stream position. | |
131 | */ | |
132 | virtual wxFileOffset OnSysTell() const; | |
133 | }; | |
134 | ||
135 | /** | |
136 | @class wxStreamBuffer | |
137 | ||
138 | wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer | |
139 | linked to a stream. | |
140 | ||
141 | Each stream always has one autoinitialized stream buffer, but you may | |
142 | attach more of them to the same stream. | |
143 | ||
144 | @library{wxbase} | |
145 | @category{streams} | |
146 | ||
147 | @see wxStreamBase, @ref overview_stream | |
148 | */ | |
149 | class wxStreamBuffer | |
150 | { | |
151 | public: | |
152 | /** BufMode flags */ | |
153 | enum BufMode | |
154 | { | |
155 | read, | |
156 | write, | |
157 | read_write | |
158 | }; | |
159 | ||
160 | /** | |
161 | Constructor, creates a new stream buffer using @a stream as a parent stream | |
162 | and mode as the IO mode. | |
163 | ||
164 | @param stream | |
165 | The parent stream. | |
166 | @param mode | |
167 | Can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read_write. | |
168 | ||
169 | One stream can have many stream buffers but only one is used internally | |
170 | to pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()), | |
171 | but you can call directly wxStreamBuffer::Read without any problems. | |
172 | Note that all errors and messages linked to the stream are stored in the | |
173 | stream, not the stream buffers: | |
174 | ||
175 | @code | |
176 | streambuffer.Read(...); | |
177 | streambuffer2.Read(...); | |
178 | // This call erases previous error messages set by 'streambuffer' | |
179 | // assuming that both instances are stream buffers for the same stream | |
180 | @endcode | |
181 | ||
182 | @see SetBufferIO() | |
183 | */ | |
184 | wxStreamBuffer(wxStreamBase& stream, BufMode mode); | |
185 | ||
186 | /** | |
187 | Constructor for an input buffer of the specified size. | |
188 | ||
189 | Using it is equivalent to using the constructor above with read mode | |
190 | and calling SetBufferIO() but is more convenient. | |
191 | ||
192 | @since 2.9.0 | |
193 | ||
194 | @param bufsize | |
195 | The size of buffer in bytes. | |
196 | @param stream | |
197 | The associated input stream, the buffer will be used in read mode. | |
198 | */ | |
199 | wxStreamBuffer(size_t bufsize, wxInputStream& stream); | |
200 | ||
201 | /** | |
202 | Constructor for an output buffer of the specified size. | |
203 | ||
204 | Using it is equivalent to using the constructor above with write mode | |
205 | and calling SetBufferIO() but is more convenient. | |
206 | ||
207 | @since 2.9.0 | |
208 | ||
209 | @param bufsize | |
210 | The size of buffer in bytes. | |
211 | @param stream | |
212 | The associated output stream, the buffer will be used in write mode. | |
213 | */ | |
214 | wxStreamBuffer(size_t bufsize, wxOutputStream& stream); | |
215 | ||
216 | /** | |
217 | Constructor; creates a new empty stream buffer which won't flush any data | |
218 | to a stream. mode specifies the type of the buffer (read, write, read_write). | |
219 | ||
220 | This stream buffer has the advantage to be stream independent and to work | |
221 | only on memory buffers but it is still compatible with the rest of the | |
222 | wxStream classes. You can write, read to this special stream and it will | |
223 | grow (if it is allowed by the user) its internal buffer. | |
224 | Briefly, it has all functionality of a "normal" stream. | |
225 | ||
226 | @warning | |
227 | The "read_write" mode doesn't currently work for standalone stream buffers. | |
228 | ||
229 | @see SetBufferIO() | |
230 | */ | |
231 | wxStreamBuffer(BufMode mode); | |
232 | ||
233 | /** | |
234 | Copy constructor. | |
235 | ||
236 | This method initializes the stream buffer with the data of the specified | |
237 | stream buffer. The new stream buffer has the same attributes, size, position | |
238 | and they share the same buffer. This will cause problems if the stream to | |
239 | which the stream buffer belong is destroyed and the newly cloned stream | |
240 | buffer continues to be used, trying to call functions in the (destroyed) | |
241 | stream. It is advised to use this feature only in very local area of the | |
242 | program. | |
243 | */ | |
244 | wxStreamBuffer(const wxStreamBuffer& buffer); | |
245 | ||
246 | /** | |
247 | Destructor. | |
248 | It finalizes all IO calls and frees all internal buffers if necessary. | |
249 | */ | |
250 | ~wxStreamBuffer(); | |
251 | ||
252 | /** | |
253 | Fill the IO buffer. | |
254 | */ | |
255 | bool FillBuffer(); | |
256 | ||
257 | /** | |
258 | Toggles the fixed flag. Usually this flag is toggled at the same time as | |
259 | @e flushable. This flag allows (when it has the @false value) or forbids | |
260 | (when it has the @true value) the stream buffer to resize dynamically the | |
261 | IO buffer. | |
262 | ||
263 | @see SetBufferIO() | |
264 | */ | |
265 | void Fixed(bool fixed); | |
266 | ||
267 | /** | |
268 | Flushes the IO buffer. | |
269 | */ | |
270 | bool FlushBuffer(); | |
271 | ||
272 | /** | |
273 | Toggles the flushable flag. | |
274 | If @a flushable is disabled, no data are sent to the parent stream. | |
275 | */ | |
276 | void Flushable(bool flushable); | |
277 | ||
278 | /** | |
279 | Returns a pointer on the end of the stream buffer. | |
280 | */ | |
281 | void* GetBufferEnd() const; | |
282 | ||
283 | /** | |
284 | Returns a pointer on the current position of the stream buffer. | |
285 | */ | |
286 | void* GetBufferPos() const; | |
287 | ||
288 | /** | |
289 | Returns the size of the buffer. | |
290 | */ | |
291 | size_t GetBufferSize() const; | |
292 | ||
293 | /** | |
294 | Returns a pointer on the start of the stream buffer. | |
295 | */ | |
296 | void* GetBufferStart() const; | |
297 | ||
298 | /** | |
299 | Gets a single char from the stream buffer. It acts like the Read() call. | |
300 | ||
301 | @warning | |
302 | You aren't directly notified if an error occurred during the IO call. | |
303 | ||
304 | @see Read() | |
305 | */ | |
306 | virtual char GetChar(); | |
307 | ||
308 | /** | |
309 | Returns the amount of available data in the buffer. | |
310 | */ | |
311 | size_t GetDataLeft(); | |
312 | ||
313 | /** | |
314 | Returns the current position (counted in bytes) in the stream buffer. | |
315 | */ | |
316 | size_t GetIntPosition() const; | |
317 | ||
318 | /** | |
319 | Returns the amount of bytes read during the last IO call to the parent stream. | |
320 | */ | |
321 | size_t GetLastAccess() const; | |
322 | ||
323 | /** | |
324 | Puts a single char to the stream buffer. | |
325 | ||
326 | @warning | |
327 | You aren't directly notified if an error occurred during the IO call. | |
328 | ||
329 | @see Read() | |
330 | */ | |
331 | virtual void PutChar(char c); | |
332 | ||
333 | /** | |
334 | Reads a block of the specified size and stores the data in buffer. | |
335 | This function tries to read from the buffer first and if more data has | |
336 | been requested, reads more data from the associated stream and updates | |
337 | the buffer accordingly until all requested data is read. | |
338 | ||
339 | @return It returns the size of the data read. If the returned size is | |
340 | different of the specified size, an error has occurred and | |
341 | should be tested using GetLastError(). | |
342 | */ | |
343 | virtual size_t Read(void* buffer, size_t size); | |
344 | ||
345 | /** | |
346 | Copies data to @a buffer. | |
347 | The function returns when @a buffer is full or when there isn't | |
348 | any more data in the current buffer. | |
349 | ||
350 | @see Write() | |
351 | */ | |
352 | size_t Read(wxStreamBuffer* buffer); | |
353 | ||
354 | /** | |
355 | Resets to the initial state variables concerning the buffer. | |
356 | */ | |
357 | void ResetBuffer(); | |
358 | ||
359 | /** | |
360 | Changes the current position. | |
361 | Parameter @a mode may be one of the following: | |
362 | ||
363 | - @b wxFromStart: The position is counted from the start of the stream. | |
364 | - @b wxFromCurrent: The position is counted from the current position of the stream. | |
365 | - @b wxFromEnd: The position is counted from the end of the stream. | |
366 | ||
367 | @return Upon successful completion, it returns the new offset as | |
368 | measured in bytes from the beginning of the stream. | |
369 | Otherwise, it returns ::wxInvalidOffset. | |
370 | */ | |
371 | virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode); | |
372 | ||
373 | /** | |
374 | Specifies which pointers to use for stream buffering. | |
375 | You need to pass a pointer on the start of the buffer end and another | |
376 | on the end. The object will use this buffer to cache stream data. | |
377 | It may be used also as a source/destination buffer when you create an | |
378 | empty stream buffer (See wxStreamBuffer::wxStreamBuffer). | |
379 | ||
380 | @remarks | |
381 | When you use this function, you will have to destroy the IO buffers | |
382 | yourself after the stream buffer is destroyed or don't use it anymore. | |
383 | In the case you use it with an empty buffer, the stream buffer will not | |
384 | resize it when it is full. | |
385 | ||
386 | @see wxStreamBuffer(), Fixed(), Flushable() | |
387 | */ | |
388 | void SetBufferIO(void* start, void* end, bool takeOwnership = false); | |
389 | ||
390 | /** | |
391 | Destroys or invalidates the previous IO buffer and allocates a new one of the | |
392 | specified size. | |
393 | ||
394 | @warning | |
395 | All previous pointers aren't valid anymore. | |
396 | ||
397 | @remarks | |
398 | The created IO buffer is growable by the object. | |
399 | ||
400 | @see Fixed(), Flushable() | |
401 | */ | |
402 | void SetBufferIO(size_t bufsize); | |
403 | ||
404 | /** | |
405 | Sets the current position (in bytes) in the stream buffer. | |
406 | ||
407 | @warning | |
408 | Since it is a very low-level function, there is no check on the position: | |
409 | specifying an invalid position can induce unexpected results. | |
410 | */ | |
411 | void SetIntPosition(size_t pos); | |
412 | ||
413 | /** | |
414 | Returns the parent stream of the stream buffer. | |
415 | @deprecated use GetStream() instead | |
416 | */ | |
417 | wxStreamBase* Stream(); | |
418 | ||
419 | /** | |
420 | Gets the current position in the stream. This position is calculated from | |
421 | the @e real position in the stream and from the internal buffer position: so | |
422 | it gives you the position in the @e real stream counted from the start of | |
423 | the stream. | |
424 | ||
425 | @return Returns the current position in the stream if possible, | |
426 | ::wxInvalidOffset in the other case. | |
427 | */ | |
428 | virtual wxFileOffset Tell() const; | |
429 | ||
430 | /** | |
431 | Truncates the buffer to the current position. | |
432 | ||
433 | @note Truncate() cannot be used to enlarge the buffer. This is | |
434 | usually not needed since the buffer expands automatically. | |
435 | */ | |
436 | void Truncate(); | |
437 | ||
438 | /** | |
439 | Writes a block of the specified size using data of buffer. | |
440 | The data are cached in a buffer before being sent in one block to the stream. | |
441 | */ | |
442 | virtual size_t Write(const void* buffer, size_t size); | |
443 | ||
444 | /** | |
445 | See Read(). | |
446 | */ | |
447 | size_t Write(wxStreamBuffer* buffer); | |
448 | }; | |
449 | ||
450 | ||
451 | ||
452 | /** | |
453 | @class wxOutputStream | |
454 | ||
455 | wxOutputStream is an abstract base class which may not be used directly. | |
456 | It is the base class of all streams which provide a Write() function, | |
457 | i.e. which can be used to output data (e.g. to a file, to a socket, etc). | |
458 | ||
459 | If you want to create your own output stream, you'll need to derive from this | |
460 | class and implement the protected OnSysWrite() function only. | |
461 | ||
462 | @library{wxbase} | |
463 | @category{streams} | |
464 | */ | |
465 | class wxOutputStream : public wxStreamBase | |
466 | { | |
467 | public: | |
468 | /** | |
469 | Creates a dummy wxOutputStream object. | |
470 | */ | |
471 | wxOutputStream(); | |
472 | ||
473 | /** | |
474 | Destructor. | |
475 | */ | |
476 | virtual ~wxOutputStream(); | |
477 | ||
478 | /** | |
479 | Closes the stream, returning @false if an error occurs. | |
480 | The stream is closed implicitly in the destructor if Close() is not | |
481 | called explicitly. | |
482 | ||
483 | If this stream wraps another stream or some other resource such | |
484 | as a file, then the underlying resource is closed too if it is owned | |
485 | by this stream, or left open otherwise. | |
486 | */ | |
487 | virtual bool Close(); | |
488 | ||
489 | /** | |
490 | Returns the number of bytes written during the last Write(). | |
491 | It may return 0 even if there is no error on the stream if it is | |
492 | only temporarily impossible to write to it. | |
493 | */ | |
494 | virtual size_t LastWrite() const; | |
495 | ||
496 | /** | |
497 | Puts the specified character in the output queue and increments the | |
498 | stream position. | |
499 | */ | |
500 | void PutC(char c); | |
501 | ||
502 | /** | |
503 | Changes the stream current position. | |
504 | ||
505 | @param pos | |
506 | Offset to seek to. | |
507 | @param mode | |
508 | One of wxFromStart, wxFromEnd, wxFromCurrent. | |
509 | ||
510 | @return The new stream position or ::wxInvalidOffset on error. | |
511 | */ | |
512 | virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart); | |
513 | ||
514 | /** | |
515 | Returns the current stream position. | |
516 | */ | |
517 | virtual wxFileOffset TellO() const; | |
518 | ||
519 | /** | |
520 | Writes up to the specified amount of bytes using the data of buffer. | |
521 | Note that not all data can always be written so you must check the number | |
522 | of bytes really written to the stream using LastWrite() when this function | |
523 | returns. | |
524 | ||
525 | In some cases (for example a write end of a pipe which is currently full) | |
526 | it is even possible that there is no errors and zero bytes have been written. | |
527 | This function returns a reference on the current object, so the user can | |
528 | test any states of the stream right away. | |
529 | */ | |
530 | virtual wxOutputStream& Write(const void* buffer, size_t size); | |
531 | ||
532 | /** | |
533 | Reads data from the specified input stream and stores them | |
534 | in the current stream. The data is read until an error is raised | |
535 | by one of the two streams. | |
536 | */ | |
537 | wxOutputStream& Write(wxInputStream& stream_in); | |
538 | ||
539 | /** | |
540 | Writes exactly the specified number of bytes from the buffer. | |
541 | ||
542 | Returns @true if exactly @a size bytes were written. Otherwise, returns | |
543 | @false and LastWrite() should be used to retrieve the exact amount of | |
544 | the data written if necessary. | |
545 | ||
546 | This method uses repeated calls to Write() (which may return writing | |
547 | only part of the data) if necessary. | |
548 | ||
549 | @since 2.9.5 | |
550 | */ | |
551 | bool WriteAll(const void* buffer, size_t size); | |
552 | ||
553 | protected: | |
554 | /** | |
555 | Internal function. It is called when the stream wants to write data of the | |
556 | specified size @a bufsize into the given @a buffer. | |
557 | ||
558 | It should return the size that was actually wrote (which maybe zero if | |
559 | @a bufsize is zero or if an error occurred; in this last case the internal | |
560 | variable @c m_lasterror should be appropriately set). | |
561 | */ | |
562 | size_t OnSysWrite(const void* buffer, size_t bufsize); | |
563 | }; | |
564 | ||
565 | ||
566 | /** | |
567 | @class wxInputStream | |
568 | ||
569 | wxInputStream is an abstract base class which may not be used directly. | |
570 | It is the base class of all streams which provide a Read() function, | |
571 | i.e. which can be used to read data from a source (e.g. a file, a socket, etc). | |
572 | ||
573 | If you want to create your own input stream, you'll need to derive from this | |
574 | class and implement the protected OnSysRead() function only. | |
575 | ||
576 | @library{wxbase} | |
577 | @category{streams} | |
578 | */ | |
579 | class wxInputStream : public wxStreamBase | |
580 | { | |
581 | public: | |
582 | /** | |
583 | Creates a dummy input stream. | |
584 | */ | |
585 | wxInputStream(); | |
586 | ||
587 | /** | |
588 | Destructor. | |
589 | */ | |
590 | virtual ~wxInputStream(); | |
591 | ||
592 | /** | |
593 | Returns @true if some data is available in the stream right now, so that | |
594 | calling Read() wouldn't block. | |
595 | */ | |
596 | virtual bool CanRead() const; | |
597 | ||
598 | /** | |
599 | Returns @true after an attempt has been made to read past the end of the | |
600 | stream. | |
601 | */ | |
602 | virtual bool Eof() const; | |
603 | ||
604 | /** | |
605 | Returns the first character in the input queue and removes it, | |
606 | blocking until it appears if necessary. | |
607 | ||
608 | On success returns a value between 0 - 255; on end of file returns @c wxEOF. | |
609 | */ | |
610 | int GetC(); | |
611 | ||
612 | /** | |
613 | Returns the last number of bytes read. | |
614 | */ | |
615 | virtual size_t LastRead() const; | |
616 | ||
617 | /** | |
618 | Returns the first character in the input queue without removing it. | |
619 | */ | |
620 | virtual char Peek(); | |
621 | ||
622 | /** | |
623 | Reads the specified amount of bytes and stores the data in buffer. | |
624 | To check if the call was successful you must use LastRead() to check | |
625 | if this call did actually read @a size bytes (if it didn't, GetLastError() | |
626 | should return a meaningful value). | |
627 | ||
628 | @warning | |
629 | The buffer absolutely needs to have at least the specified size. | |
630 | ||
631 | @return This function returns a reference on the current object, so the | |
632 | user can test any states of the stream right away. | |
633 | */ | |
634 | virtual wxInputStream& Read(void* buffer, size_t size); | |
635 | ||
636 | /** | |
637 | Reads data from the input queue and stores it in the specified output stream. | |
638 | The data is read until an error is raised by one of the two streams. | |
639 | ||
640 | @return This function returns a reference on the current object, so the | |
641 | user can test any states of the stream right away. | |
642 | */ | |
643 | wxInputStream& Read(wxOutputStream& stream_out); | |
644 | ||
645 | /** | |
646 | Reads exactly the specified number of bytes into the buffer. | |
647 | ||
648 | Returns @true only if the entire amount of data was read, otherwise | |
649 | @false is returned and the number of bytes really read can be retrieved | |
650 | using LastRead(), as with Read(). | |
651 | ||
652 | This method uses repeated calls to Read() (which may return after | |
653 | reading less than the requested number of bytes) if necessary. | |
654 | ||
655 | @warning | |
656 | The buffer absolutely needs to have at least the specified size. | |
657 | ||
658 | @since 2.9.5 | |
659 | */ | |
660 | bool ReadAll(void* buffer, size_t size); | |
661 | ||
662 | /** | |
663 | Changes the stream current position. | |
664 | ||
665 | This operation in general is possible only for seekable streams | |
666 | (see wxStreamBase::IsSeekable()); non-seekable streams support only | |
667 | seeking positive amounts in mode @c wxFromCurrent (this is implemented | |
668 | by reading data and simply discarding it). | |
669 | ||
670 | @param pos | |
671 | Offset to seek to. | |
672 | @param mode | |
673 | One of wxFromStart, wxFromEnd, wxFromCurrent. | |
674 | ||
675 | @return The new stream position or ::wxInvalidOffset on error. | |
676 | */ | |
677 | virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart); | |
678 | ||
679 | /** | |
680 | Returns the current stream position or ::wxInvalidOffset if it's not | |
681 | available (e.g. socket streams do not have a size nor a current stream | |
682 | position). | |
683 | */ | |
684 | virtual wxFileOffset TellI() const; | |
685 | ||
686 | /** | |
687 | This function is only useful in read mode. | |
688 | It is the manager of the "Write-Back" buffer. This buffer acts like a | |
689 | temporary buffer where data which has to be read during the next read IO | |
690 | call are put. This is useful when you get a big block of data which you | |
691 | didn't want to read: you can replace them at the top of the input queue | |
692 | by this way. | |
693 | ||
694 | Be very careful about this call in connection with calling SeekI() on | |
695 | the same stream. Any call to SeekI() will invalidate any previous call | |
696 | to this method (otherwise you could SeekI() to one position, "unread" a | |
697 | few bytes there, SeekI() to another position and data would be either | |
698 | lost or corrupted). | |
699 | ||
700 | @return Returns the amount of bytes saved in the Write-Back buffer. | |
701 | */ | |
702 | size_t Ungetch(const void* buffer, size_t size); | |
703 | ||
704 | /** | |
705 | This function acts like the previous one except that it takes only one | |
706 | character: it is sometimes shorter to use than the generic function. | |
707 | */ | |
708 | bool Ungetch(char c); | |
709 | ||
710 | protected: | |
711 | ||
712 | /** | |
713 | Internal function. It is called when the stream wants to read data of the | |
714 | specified size @a bufsize and wants it to be placed inside @a buffer. | |
715 | ||
716 | It should return the size that was actually read or zero if EOF has been | |
717 | reached or an error occurred (in this last case the internal @c m_lasterror | |
718 | variable should be set accordingly as well). | |
719 | */ | |
720 | size_t OnSysRead(void* buffer, size_t bufsize) = 0; | |
721 | }; | |
722 | ||
723 | ||
724 | ||
725 | ||
726 | /** | |
727 | @class wxCountingOutputStream | |
728 | ||
729 | wxCountingOutputStream is a specialized output stream which does not write any | |
730 | data anywhere, instead it counts how many bytes would get written if this were a | |
731 | normal stream. This can sometimes be useful or required if some data gets | |
732 | serialized to a stream or compressed by using stream compression and thus the | |
733 | final size of the stream cannot be known other than pretending to write the stream. | |
734 | One case where the resulting size would have to be known is if the data has | |
735 | to be written to a piece of memory and the memory has to be allocated before | |
736 | writing to it (which is probably always the case when writing to a memory stream). | |
737 | ||
738 | @library{wxbase} | |
739 | @category{streams} | |
740 | */ | |
741 | class wxCountingOutputStream : public wxOutputStream | |
742 | { | |
743 | public: | |
744 | /** | |
745 | Creates a wxCountingOutputStream object. | |
746 | */ | |
747 | wxCountingOutputStream(); | |
748 | ||
749 | /** | |
750 | Destructor. | |
751 | */ | |
752 | virtual ~wxCountingOutputStream(); | |
753 | ||
754 | /** | |
755 | Returns the current length of the stream. | |
756 | ||
757 | This is the amount of data written to the stream so far, in bytes. | |
758 | */ | |
759 | virtual wxFileOffset GetLength() const; | |
760 | }; | |
761 | ||
762 | ||
763 | /** | |
764 | @class wxBufferedInputStream | |
765 | ||
766 | This stream acts as a cache. It caches the bytes read from the specified | |
767 | input stream (see wxFilterInputStream). | |
768 | It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes. | |
769 | This class may not be used without some other stream to read the data | |
770 | from (such as a file stream or a memory stream). | |
771 | ||
772 | @library{wxbase} | |
773 | @category{streams} | |
774 | ||
775 | @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream | |
776 | */ | |
777 | class wxBufferedInputStream : public wxFilterInputStream | |
778 | { | |
779 | public: | |
780 | /** | |
781 | Constructor using the provided buffer or default. | |
782 | ||
783 | @param stream | |
784 | The associated low-level stream. | |
785 | @param buffer | |
786 | The buffer to use if non-@NULL. Notice that the ownership of this | |
787 | buffer is taken by the stream, i.e. it will delete it. If this | |
788 | parameter is @NULL a default 1KB buffer is used. | |
789 | */ | |
790 | wxBufferedInputStream(wxInputStream& stream, | |
791 | wxStreamBuffer *buffer = NULL); | |
792 | ||
793 | /** | |
794 | Constructor allowing to specify the size of the buffer. | |
795 | ||
796 | This is just a more convenient alternative to creating a wxStreamBuffer | |
797 | of the given size and using the other overloaded constructor of this | |
798 | class. | |
799 | ||
800 | @param stream | |
801 | The associated low-level stream. | |
802 | @param bufsize | |
803 | The size of the buffer, in bytes. | |
804 | ||
805 | @since 2.9.0 | |
806 | */ | |
807 | wxBufferedInputStream(wxInputStream& stream, size_t bufsize); | |
808 | ||
809 | /** | |
810 | Destructor. | |
811 | */ | |
812 | virtual ~wxBufferedInputStream(); | |
813 | }; | |
814 | ||
815 | ||
816 | ||
817 | ||
818 | /** | |
819 | Enumeration values used by wxFilterClassFactory. | |
820 | */ | |
821 | enum wxStreamProtocolType | |
822 | { | |
823 | wxSTREAM_PROTOCOL, //!< wxFileSystem protocol (should be only one). | |
824 | wxSTREAM_MIMETYPE, //!< MIME types the stream handles. | |
825 | wxSTREAM_ENCODING, //!< The HTTP Content-Encodings the stream handles. | |
826 | wxSTREAM_FILEEXT //!< File extensions the stream handles. | |
827 | }; | |
828 | ||
829 | /** | |
830 | @class wxFilterClassFactory | |
831 | ||
832 | Allows the creation of filter streams to handle compression formats such | |
833 | as gzip and bzip2. | |
834 | ||
835 | For example, given a filename you can search for a factory that will | |
836 | handle it and create a stream to decompress it: | |
837 | ||
838 | @code | |
839 | factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); | |
840 | if (factory) | |
841 | stream = factory->NewStream(new wxFFileInputStream(filename)); | |
842 | @endcode | |
843 | ||
844 | wxFilterClassFactory::Find can also search for a factory by MIME type, | |
845 | HTTP encoding or by wxFileSystem protocol. | |
846 | The available factories can be enumerated using wxFilterClassFactory::GetFirst() | |
847 | and wxFilterClassFactory::GetNext(). | |
848 | ||
849 | @library{wxbase} | |
850 | @category{streams} | |
851 | ||
852 | @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, | |
853 | @ref overview_archive | |
854 | */ | |
855 | class wxFilterClassFactory : public wxObject | |
856 | { | |
857 | public: | |
858 | /** | |
859 | Returns @true if this factory can handle the given protocol, MIME type, HTTP | |
860 | encoding or file extension. | |
861 | ||
862 | When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter | |
863 | can be a complete filename rather than just an extension. | |
864 | */ | |
865 | bool CanHandle(const wxString& protocol, | |
866 | wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; | |
867 | ||
868 | /** | |
869 | A static member that finds a factory that can handle a given protocol, MIME | |
870 | type, HTTP encoding or file extension. Returns a pointer to the class | |
871 | factory if found, or @NULL otherwise. | |
872 | It does not give away ownership of the factory. | |
873 | ||
874 | When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter | |
875 | can be a complete filename rather than just an extension. | |
876 | */ | |
877 | static const wxFilterClassFactory* Find(const wxString& protocol, | |
878 | wxStreamProtocolType type = wxSTREAM_PROTOCOL); | |
879 | ||
880 | //@{ | |
881 | /** | |
882 | GetFirst and GetNext can be used to enumerate the available factories. | |
883 | For example, to list them: | |
884 | ||
885 | @code | |
886 | wxString list; | |
887 | const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst(); | |
888 | ||
889 | while (factory) { | |
890 | list << factory->GetProtocol() << wxT("\n"); | |
891 | factory = factory->GetNext(); | |
892 | } | |
893 | @endcode | |
894 | ||
895 | GetFirst()/GetNext() return a pointer to a factory or @NULL if no more | |
896 | are available. They do not give away ownership of the factory. | |
897 | */ | |
898 | static const wxFilterClassFactory* GetFirst(); | |
899 | const wxFilterClassFactory* GetNext() const; | |
900 | //@} | |
901 | ||
902 | /** | |
903 | Returns the wxFileSystem protocol supported by this factory. | |
904 | Equivalent to @code wxString(*GetProtocols()) @endcode. | |
905 | */ | |
906 | wxString GetProtocol() const; | |
907 | ||
908 | /** | |
909 | Returns the protocols, MIME types, HTTP encodings or file extensions | |
910 | supported by this factory, as an array of null terminated strings. | |
911 | It does not give away ownership of the array or strings. | |
912 | ||
913 | For example, to list the file extensions a factory supports: | |
914 | ||
915 | @code | |
916 | wxString list; | |
917 | const wxChar *const *p; | |
918 | ||
919 | for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++) | |
920 | list << *p << wxT("\n"); | |
921 | @endcode | |
922 | */ | |
923 | virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0; | |
924 | ||
925 | //@{ | |
926 | /** | |
927 | Create a new input or output stream to decompress or compress a given stream. | |
928 | ||
929 | If the parent stream is passed as a pointer then the new filter stream | |
930 | takes ownership of it. If it is passed by reference then it does not. | |
931 | */ | |
932 | virtual wxFilterInputStream* NewStream(wxInputStream& stream) const = 0; | |
933 | virtual wxFilterOutputStream* NewStream(wxOutputStream& stream) const = 0; | |
934 | virtual wxFilterInputStream* NewStream(wxInputStream* stream) const = 0; | |
935 | virtual wxFilterOutputStream* NewStream(wxOutputStream* stream) const = 0; | |
936 | //@} | |
937 | ||
938 | /** | |
939 | Remove the file extension of @a location if it is one of the file | |
940 | extensions handled by this factory. | |
941 | */ | |
942 | wxString PopExtension(const wxString& location) const; | |
943 | ||
944 | /** | |
945 | Adds this class factory to the list returned by GetFirst()/GetNext(). | |
946 | ||
947 | It is not necessary to do this to use the filter streams. It is usually | |
948 | used when implementing streams, typically the implementation will | |
949 | add a static instance of its factory class. | |
950 | ||
951 | It can also be used to change the order of a factory already in the list, | |
952 | bringing it to the front. This isn't a thread safe operation so can't be | |
953 | done when other threads are running that will be using the list. | |
954 | ||
955 | The list does not take ownership of the factory. | |
956 | */ | |
957 | void PushFront(); | |
958 | ||
959 | /** | |
960 | Removes this class factory from the list returned by GetFirst()/GetNext(). | |
961 | Removing from the list isn't a thread safe operation so can't be done | |
962 | when other threads are running that will be using the list. | |
963 | ||
964 | The list does not own the factories, so removing a factory does not delete it. | |
965 | */ | |
966 | void Remove(); | |
967 | }; | |
968 | ||
969 | ||
970 | ||
971 | /** | |
972 | @class wxFilterOutputStream | |
973 | ||
974 | A filter stream has the capability of a normal stream but it can be placed | |
975 | on top of another stream. So, for example, it can compress, encrypt the data | |
976 | which are passed to it and write them to another stream. | |
977 | ||
978 | @note | |
979 | The use of this class is exactly the same as of wxOutputStream. | |
980 | Only a constructor differs and it is documented below. | |
981 | ||
982 | @library{wxbase} | |
983 | @category{streams} | |
984 | ||
985 | @see wxFilterClassFactory, wxFilterInputStream | |
986 | */ | |
987 | class wxFilterOutputStream : public wxOutputStream | |
988 | { | |
989 | public: | |
990 | //@{ | |
991 | /** | |
992 | Initializes a "filter" stream. | |
993 | ||
994 | If the parent stream is passed as a pointer then the new filter stream | |
995 | takes ownership of it. If it is passed by reference then it does not. | |
996 | */ | |
997 | wxFilterOutputStream(wxOutputStream& stream); | |
998 | wxFilterOutputStream(wxOutputStream* stream); | |
999 | //@} | |
1000 | }; | |
1001 | ||
1002 | ||
1003 | ||
1004 | /** | |
1005 | @class wxFilterInputStream | |
1006 | ||
1007 | A filter stream has the capability of a normal stream but it can be placed on | |
1008 | top of another stream. So, for example, it can uncompress or decrypt the data which | |
1009 | are read from another stream and pass it to the requester. | |
1010 | ||
1011 | @note | |
1012 | The interface of this class is the same as that of wxInputStream. | |
1013 | Only a constructor differs and it is documented below. | |
1014 | ||
1015 | @library{wxbase} | |
1016 | @category{streams} | |
1017 | ||
1018 | @see wxFilterClassFactory, wxFilterOutputStream | |
1019 | */ | |
1020 | class wxFilterInputStream : public wxInputStream | |
1021 | { | |
1022 | public: | |
1023 | //@{ | |
1024 | /** | |
1025 | Initializes a "filter" stream. | |
1026 | ||
1027 | If the parent stream is passed as a pointer then the new filter stream | |
1028 | takes ownership of it. If it is passed by reference then it does not. | |
1029 | */ | |
1030 | wxFilterInputStream(wxInputStream& stream); | |
1031 | wxFilterInputStream(wxInputStream* stream); | |
1032 | //@} | |
1033 | }; | |
1034 | ||
1035 | ||
1036 | ||
1037 | /** | |
1038 | @class wxBufferedOutputStream | |
1039 | ||
1040 | This stream acts as a cache. It caches the bytes to be written to the specified | |
1041 | output stream (See wxFilterOutputStream). The data is only written when the | |
1042 | cache is full, when the buffered stream is destroyed or when calling SeekO(). | |
1043 | ||
1044 | This class may not be used without some other stream to write the data | |
1045 | to (such as a file stream or a memory stream). | |
1046 | ||
1047 | @library{wxbase} | |
1048 | @category{streams} | |
1049 | ||
1050 | @see wxStreamBuffer, wxOutputStream | |
1051 | */ | |
1052 | class wxBufferedOutputStream : public wxFilterOutputStream | |
1053 | { | |
1054 | public: | |
1055 | /** | |
1056 | Constructor using the provided buffer or default. | |
1057 | ||
1058 | @param stream | |
1059 | The associated low-level stream. | |
1060 | @param buffer | |
1061 | The buffer to use if non-@NULL. Notice that the ownership of this | |
1062 | buffer is taken by the stream, i.e. it will delete it. If this | |
1063 | parameter is @NULL a default 1KB buffer is used. | |
1064 | */ | |
1065 | wxBufferedOutputStream(wxOutputStream& stream, | |
1066 | wxStreamBuffer *buffer = NULL); | |
1067 | ||
1068 | /** | |
1069 | Constructor allowing to specify the size of the buffer. | |
1070 | ||
1071 | This is just a more convenient alternative to creating a wxStreamBuffer | |
1072 | of the given size and using the other overloaded constructor of this | |
1073 | class. | |
1074 | ||
1075 | @param stream | |
1076 | The associated low-level stream. | |
1077 | @param bufsize | |
1078 | The size of the buffer, in bytes. | |
1079 | ||
1080 | @since 2.9.0 | |
1081 | */ | |
1082 | wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize); | |
1083 | ||
1084 | /** | |
1085 | Destructor. Calls Sync() and destroys the internal buffer. | |
1086 | */ | |
1087 | virtual ~wxBufferedOutputStream(); | |
1088 | ||
1089 | /** | |
1090 | Calls Sync() and changes the stream position. | |
1091 | */ | |
1092 | virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart); | |
1093 | ||
1094 | /** | |
1095 | Flushes the buffer and calls Sync() on the parent stream. | |
1096 | */ | |
1097 | virtual void Sync(); | |
1098 | }; | |
1099 | ||
1100 | ||
1101 | /** | |
1102 | @class wxWrapperInputStream | |
1103 | ||
1104 | A wrapper input stream is a kind of filter stream which forwards all the | |
1105 | operations to its base stream. This is useful to build utility classes such | |
1106 | as wxFSInputStream. | |
1107 | ||
1108 | @note | |
1109 | The interface of this class is the same as that of wxInputStream. | |
1110 | Only a constructor differs and it is documented below. | |
1111 | ||
1112 | @library{wxbase} | |
1113 | @category{streams} | |
1114 | ||
1115 | @see wxFSInputStream, wxFilterInputStream | |
1116 | @since 2.9.4 | |
1117 | */ | |
1118 | class wxWrapperInputStream : public wxFilterInputStream | |
1119 | { | |
1120 | public: | |
1121 | //@{ | |
1122 | /** | |
1123 | Initializes a wrapper stream. | |
1124 | ||
1125 | If the parent stream is passed as a pointer then the new wrapper stream | |
1126 | takes ownership of it. If it is passed by reference then it does not. | |
1127 | */ | |
1128 | wxWrapperInputStream(wxInputStream& stream); | |
1129 | wxWrapperInputStream(wxInputStream* stream); | |
1130 | //@} | |
1131 | ||
1132 | protected: | |
1133 | /** | |
1134 | Default constructor, use InitParentStream() to finish initialization. | |
1135 | ||
1136 | This constructor can be used by the derived classes from their own | |
1137 | constructors when the parent stream can't be specified immediately. | |
1138 | The derived class must call InitParentStream() later to do it. | |
1139 | */ | |
1140 | wxWrapperInputStream(); | |
1141 | ||
1142 | //@{ | |
1143 | /** | |
1144 | Set up the wrapped stream for an object initialized using the default | |
1145 | constructor. | |
1146 | ||
1147 | The ownership logic is the same as for the non-default constructor, | |
1148 | i.e. this object takes ownership of the stream if it's passed by | |
1149 | pointer but not if it's passed by reference. | |
1150 | */ | |
1151 | void InitParentStream(wxInputStream& stream); | |
1152 | void InitParentStream(wxInputStream* stream); | |
1153 | //@} | |
1154 | }; |