]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/stream.h
fixing typo (lead to always floating layering for simple frames)
[wxWidgets.git] / interface / wx / stream.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: stream.h
3 // Purpose: interface of wxCountingOutputStream
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxCountingOutputStream
11
12 wxCountingOutputStream is a specialized output stream which does not write any
13 data anywhere,
14 instead it counts how many bytes would get written if this were a normal
15 stream. This
16 can sometimes be useful or required if some data gets serialized to a stream or
17 compressed
18 by using stream compression and thus the final size of the stream cannot be
19 known other
20 than pretending to write the stream. One case where the resulting size would
21 have to be
22 known is if the data has to be written to a piece of memory and the memory has
23 to be
24 allocated before writing to it (which is probably always the case when writing
25 to a
26 memory stream).
27
28 @library{wxbase}
29 @category{streams}
30 */
31 class wxCountingOutputStream : public wxOutputStream
32 {
33 public:
34 /**
35 Creates a wxCountingOutputStream object.
36 */
37 wxCountingOutputStream();
38
39 /**
40 Destructor.
41 */
42 ~wxCountingOutputStream();
43
44 /**
45 Returns the current size of the stream.
46 */
47 size_t GetSize() const;
48 };
49
50
51
52 /**
53 @class wxBufferedInputStream
54
55 This stream acts as a cache. It caches the bytes read from the specified
56 input stream (See wxFilterInputStream).
57 It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
58 This class may not be used without some other stream to read the data
59 from (such as a file stream or a memory stream).
60
61 @library{wxbase}
62 @category{streams}
63
64 @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
65 */
66 class wxBufferedInputStream : public wxFilterInputStream
67 {
68 public:
69
70 };
71
72
73
74 /**
75 @class wxStreamBuffer
76
77
78 @library{wxbase}
79 @category{streams}
80
81 @see wxStreamBase
82 */
83 class wxStreamBuffer
84 {
85 public:
86 //@{
87 /**
88 Constructor. It initializes the stream buffer with the data of the specified
89 stream buffer. The new stream buffer has the same attributes, size, position
90 and they share the same buffer. This will cause problems if the stream to
91 which the stream buffer belong is destroyed and the newly cloned stream
92 buffer continues to be used, trying to call functions in the (destroyed)
93 stream. It is advised to use this feature only in very local area of the
94 program.
95
96 @see @ref setbufferio() wxStreamBuffer:SetBufferIO
97 */
98 wxStreamBuffer(wxStreamBase& stream, BufMode mode);
99 wxStreamBuffer(BufMode mode);
100 wxStreamBuffer(const wxStreamBuffer& buffer);
101 //@}
102
103 /**
104 Destructor. It finalizes all IO calls and frees all internal buffers if
105 necessary.
106 */
107 wxStreamBuffer();
108
109 /**
110 Fill the IO buffer.
111 */
112 bool FillBuffer();
113
114 /**
115 Toggles the fixed flag. Usually this flag is toggled at the same time as
116 @e flushable. This flag allows (when it has the @false value) or forbids
117 (when it has the @true value) the stream buffer to resize dynamically the IO
118 buffer.
119
120 @see SetBufferIO()
121 */
122 void Fixed(bool fixed);
123
124 /**
125 Flushes the IO buffer.
126 */
127 bool FlushBuffer();
128
129 /**
130 Toggles the flushable flag. If @a flushable is disabled, no data are sent
131 to the parent stream.
132 */
133 void Flushable(bool flushable);
134
135 /**
136 Returns a pointer on the end of the stream buffer.
137 */
138 void* GetBufferEnd() const;
139
140 /**
141 Returns a pointer on the current position of the stream buffer.
142 */
143 void* GetBufferPos() const;
144
145 /**
146 Returns the size of the buffer.
147 */
148 size_t GetBufferSize() const;
149
150 /**
151 Returns a pointer on the start of the stream buffer.
152 */
153 void* GetBufferStart() const;
154
155 /**
156 Gets a single char from the stream buffer. It acts like the Read call.
157
158 @see Read()
159 */
160 char GetChar();
161
162 /**
163 Returns the amount of available data in the buffer.
164 */
165 size_t GetDataLeft();
166
167 /**
168 Returns the current position (counted in bytes) in the stream buffer.
169 */
170 off_t GetIntPosition() const;
171
172 /**
173 Returns the amount of bytes read during the last IO call to the parent stream.
174 */
175 size_t GetLastAccess() const;
176
177 /**
178 Puts a single char to the stream buffer.
179
180 @see Read()
181 */
182 void PutChar(char c);
183
184 //@{
185 /**
186 Copies data to @e buffer. The function returns when @a buffer is full or when
187 there isn't
188 any more data in the current buffer.
189
190 @see Write()
191 */
192 size_t Read(void* buffer, size_t size);
193 Return value size_t Read(wxStreamBuffer* buffer);
194 //@}
195
196 /**
197 Resets to the initial state variables concerning the buffer.
198 */
199 void ResetBuffer();
200
201 /**
202 Changes the current position.
203 @a mode may be one of the following:
204
205 @b wxFromStart
206
207 The position is counted from the start of the stream.
208
209 @b wxFromCurrent
210
211 The position is counted from the current position of the stream.
212
213 @b wxFromEnd
214
215 The position is counted from the end of the stream.
216
217 @return Upon successful completion, it returns the new offset as
218 measured in bytes from the beginning of the stream.
219 Otherwise, it returns wxInvalidOffset.
220 */
221 off_t Seek(off_t pos, wxSeekMode mode);
222
223 //@{
224 /**
225 Destroys or invalidates the previous IO buffer and allocates a new one of the
226 specified size.
227
228 @see Fixed(), Flushable()
229 */
230 void SetBufferIO(char* buffer_start, char* buffer_end);
231 Remarks See also
232 wxStreamBuffer constructor
233
234 wxStreamBuffer::Fixed
235
236 wxStreamBuffer::Flushable
237 void SetBufferIO(size_t bufsize);
238 //@}
239
240 /**
241 Sets the current position (in bytes) in the stream buffer.
242 */
243 void SetIntPosition(size_t pos);
244
245 /**
246 Returns the parent stream of the stream buffer.
247 */
248 wxStreamBase* Stream();
249
250 /**
251 Gets the current position in the stream. This position is calculated from
252 the @e real position in the stream and from the internal buffer position: so
253 it gives you the position in the @e real stream counted from the start of
254 the stream.
255
256 @return Returns the current position in the stream if possible,
257 wxInvalidOffset in the other case.
258 */
259 off_t Tell() const;
260
261 /**
262 Truncates the buffer to the current position.
263 Note: Truncate() cannot be used to enlarge the buffer. This is
264 usually not needed since the buffer expands automatically.
265 */
266 void Truncate();
267
268 //@{
269 /**
270 See Read().
271 */
272 size_t Write(const void* buffer, size_t size);
273 size_t Write(wxStreamBuffer* buffer);
274 //@}
275 };
276
277
278
279 /**
280 @class wxOutputStream
281
282 wxOutputStream is an abstract base class which may not be used directly.
283
284 @library{wxbase}
285 @category{streams}
286 */
287 class wxOutputStream : public wxStreamBase
288 {
289 public:
290 /**
291 Creates a dummy wxOutputStream object.
292 */
293 wxOutputStream();
294
295 /**
296 Destructor.
297 */
298 ~wxOutputStream();
299
300 /**
301 Closes the stream, returning @false if an error occurs. The
302 stream is closed implicitly in the destructor if Close() is not
303 called explicitly.
304 If this stream wraps another stream or some other resource such
305 as a file, then the underlying resource is closed too if it is owned
306 by this stream, or left open otherwise.
307 */
308 bool Close();
309
310 /**
311 Returns the number of bytes written during the last
312 Write(). It may return 0 even if there is no
313 error on the stream if it is only temporarily impossible to write to it.
314 */
315 size_t LastWrite() const;
316
317 /**
318 Puts the specified character in the output queue and increments the
319 stream position.
320 */
321 void PutC(char c);
322
323 /**
324 Changes the stream current position.
325
326 @param pos
327 Offset to seek to.
328 @param mode
329 One of wxFromStart, wxFromEnd, wxFromCurrent.
330
331 @return The new stream position or wxInvalidOffset on error.
332 */
333 off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart);
334
335 /**
336 Returns the current stream position.
337 */
338 off_t TellO() const;
339
340 //@{
341 /**
342 Reads data from the specified input stream and stores them
343 in the current stream. The data is read until an error is raised
344 by one of the two streams.
345 */
346 wxOutputStream Write(const void* buffer, size_t size);
347 wxOutputStream Write(wxInputStream& stream_in);
348 //@}
349 };
350
351
352
353 /**
354 @class wxFilterClassFactory
355
356 Allows the creation of filter streams to handle compression formats such
357 as gzip and bzip2.
358
359 For example, given a filename you can search for a factory that will
360 handle it and create a stream to decompress it:
361
362 @code
363 factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
364 if (factory)
365 stream = factory-NewStream(new wxFFileInputStream(filename));
366 @endcode
367
368 wxFilterClassFactory::Find can also search
369 for a factory by MIME type, HTTP encoding or by wxFileSystem protocol.
370 The available factories can be enumerated
371 using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext".
372
373 @library{wxbase}
374 @category{FIXME}
375
376 @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref
377 overview_wxarc "Archive formats such as zip"
378 */
379 class wxFilterClassFactory : public wxObject
380 {
381 public:
382 /**
383 Returns @true if this factory can handle the given protocol, MIME type, HTTP
384 encoding or file extension.
385 When using wxSTREAM_FILEEXT for the second parameter, the first parameter
386 can be a complete filename rather than just an extension.
387 */
388 bool CanHandle(const wxString& protocol,
389 wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
390
391 /**
392 A static member that finds a factory that can handle a given protocol, MIME
393 type, HTTP encoding or file extension. Returns a pointer to the class
394 factory if found, or @NULL otherwise. It does not give away ownership of the
395 factory.
396 When using wxSTREAM_FILEEXT for the second parameter, the first parameter
397 can be a complete filename rather than just an extension.
398 */
399 static const wxFilterClassFactory* Find(const wxString& protocol,
400 wxStreamProtocolType type = wxSTREAM_PROTOCOL);
401
402 //@{
403 /**
404 GetFirst and GetNext can be used to enumerate the available factories.
405 For example, to list them:
406
407 GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
408 are available. They do not give away ownership of the factory.
409 */
410 static const wxFilterClassFactory* GetFirst() const;
411 const wxFilterClassFactory* GetNext() const;
412 //@}
413
414 /**
415 Returns the wxFileSystem protocol supported by this factory. Equivalent
416 to wxString(*GetProtcols()).
417 */
418 wxString GetProtocol() const;
419
420 /**
421 Returns the protocols, MIME types, HTTP encodings or file extensions
422 supported by this factory, as an array of null terminated strings. It does
423 not give away ownership of the array or strings.
424 For example, to list the file extensions a factory supports:
425 */
426 const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
427
428 //@{
429 /**
430 Create a new input or output stream to decompress or compress a given stream.
431 If the parent stream is passed as a pointer then the new filter stream
432 takes ownership of it. If it is passed by reference then it does not.
433 */
434 wxFilterInputStream* NewStream(wxInputStream& stream) const;
435 const wxFilterOutputStream* NewStream(wxOutputStream& stream) const;
436 const wxFilterInputStream* NewStream(wxInputStream* stream) const;
437 const wxFilterOutputStream* NewStream(wxOutputStream* stream) const;
438 //@}
439
440 /**
441 Remove the file extension of @a location if it is one of the file
442 extensions handled by this factory.
443 */
444 wxString PopExtension(const wxString& location) const;
445
446 /**
447 Adds this class factory to the list returned
448 by @ref getfirst() GetFirst()/GetNext.
449 It is not necessary to do this to use the filter streams. It is usually
450 used when implementing streams, typically the implementation will
451 add a static instance of its factory class.
452 It can also be used to change the order of a factory already in the list,
453 bringing it to the front. This isn't a thread safe operation
454 so can't be done when other threads are running that will be using the list.
455 The list does not take ownership of the factory.
456 */
457 void PushFront();
458
459 /**
460 Removes this class factory from the list returned
461 by @ref getfirst() GetFirst()/GetNext.
462 Removing from the list isn't a thread safe operation
463 so can't be done when other threads are running that will be using the list.
464 The list does not own the factories, so removing a factory does not delete it.
465 */
466 void Remove();
467 };
468
469
470
471 /**
472 @class wxFilterOutputStream
473
474 A filter stream has the capability of a normal
475 stream but it can be placed on top of another stream. So, for example, it
476 can compress, encrypt the data which are passed to it and write them to another
477 stream.
478
479 @library{wxbase}
480 @category{streams}
481
482 @see wxFilterClassFactory, wxFilterInputStream
483 */
484 class wxFilterOutputStream : public wxOutputStream
485 {
486 public:
487 //@{
488 /**
489 Initializes a "filter" stream.
490 If the parent stream is passed as a pointer then the new filter stream
491 takes ownership of it. If it is passed by reference then it does not.
492 */
493 wxFilterOutputStream(wxOutputStream& stream);
494 wxFilterOutputStream(wxOutputStream* stream);
495 //@}
496 };
497
498
499
500 /**
501 @class wxFilterInputStream
502
503 A filter stream has the capability of a normal stream but it can be placed on
504 top
505 of another stream. So, for example, it can uncompress or decrypt the data which
506 are read
507 from another stream and pass it to the requester.
508
509 @library{wxbase}
510 @category{streams}
511
512 @see wxFilterClassFactory, wxFilterOutputStream
513 */
514 class wxFilterInputStream : public wxInputStream
515 {
516 public:
517 //@{
518 /**
519 Initializes a "filter" stream.
520 If the parent stream is passed as a pointer then the new filter stream
521 takes ownership of it. If it is passed by reference then it does not.
522 */
523 wxFilterInputStream(wxInputStream& stream);
524 wxFilterInputStream(wxInputStream* stream);
525 //@}
526 };
527
528
529
530 /**
531 @class wxBufferedOutputStream
532
533 This stream acts as a cache. It caches the bytes to be written to the specified
534 output stream (See wxFilterOutputStream). The
535 data is only written when the cache is full, when the buffered stream is
536 destroyed or when calling SeekO().
537
538 This class may not be used without some other stream to write the data
539 to (such as a file stream or a memory stream).
540
541 @library{wxbase}
542 @category{streams}
543
544 @see wxStreamBuffer, wxOutputStream
545 */
546 class wxBufferedOutputStream : public wxFilterOutputStream
547 {
548 public:
549 /**
550 Creates a buffered stream using a buffer of a default size of 1024 bytes for
551 cashing
552 the stream @e parent.
553 */
554 wxBufferedOutputStream(const wxOutputStream& parent);
555
556 /**
557 Destructor. Calls Sync() and destroys the internal buffer.
558 */
559 ~wxBufferedOutputStream();
560
561 /**
562 Calls Sync() and changes the stream position.
563 */
564 off_t SeekO(off_t pos, wxSeekMode mode);
565
566 /**
567 Flushes the buffer and calls Sync() on the parent stream.
568 */
569 void Sync();
570 };
571
572
573
574 /**
575 @class wxInputStream
576
577 wxInputStream is an abstract base class which may not be used directly.
578
579 @library{wxbase}
580 @category{streams}
581 */
582 class wxInputStream : public wxStreamBase
583 {
584 public:
585 /**
586 Creates a dummy input stream.
587 */
588 wxInputStream();
589
590 /**
591 Destructor.
592 */
593 ~wxInputStream();
594
595 /**
596 Returns @true if some data is available in the stream right now, so that
597 calling Read() wouldn't block.
598 */
599 bool CanRead() const;
600
601 /**
602 Returns @true after an attempt has been made to read past the end of the
603 stream.
604 */
605 bool Eof() const;
606
607 /**
608 Returns the first character in the input queue and removes it,
609 blocking until it appears if necessary.
610 */
611 char GetC();
612
613 /**
614 Returns the last number of bytes read.
615 */
616 size_t LastRead() const;
617
618 /**
619 Returns the first character in the input queue without removing it.
620 */
621 char Peek();
622
623 //@{
624 /**
625 Reads data from the input queue and stores it in the specified output stream.
626 The data is read until an error is raised by one of the two streams.
627
628 @return This function returns a reference on the current object, so the
629 user can test any states of the stream right away.
630 */
631 wxInputStream Read(void* buffer, size_t size);
632 Warning Return value
633 This function returns a reference on the current object, so the user can test
634 any states of the stream right away.
635 wxInputStream& Read(wxOutputStream& stream_out);
636 //@}
637
638 /**
639 Changes the stream current position.
640
641 @param pos
642 Offset to seek to.
643 @param mode
644 One of wxFromStart, wxFromEnd, wxFromCurrent.
645
646 @return The new stream position or wxInvalidOffset on error.
647 */
648 off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart);
649
650 /**
651 Returns the current stream position.
652 */
653 off_t TellI() const;
654
655 //@{
656 /**
657 This function acts like the previous one except that it takes only one
658 character: it is sometimes shorter to use than the generic function.
659 */
660 size_t Ungetch(const char* buffer, size_t size);
661 Return value bool Ungetch(char c);
662 //@}
663 };
664
665
666
667 /**
668 @class wxStreamBase
669
670 This class is the base class of most stream related classes in wxWidgets. It
671 must
672 not be used directly.
673
674 @library{wxbase}
675 @category{streams}
676
677 @see wxStreamBuffer
678 */
679 class wxStreamBase
680 {
681 public:
682 /**
683 Creates a dummy stream object. It doesn't do anything.
684 */
685 wxStreamBase();
686
687 /**
688 Destructor.
689 */
690 ~wxStreamBase();
691
692 /**
693 This function returns the last error.
694
695 @b wxSTREAM_NO_ERROR
696
697 No error occurred.
698
699 @b wxSTREAM_EOF
700
701 An End-Of-File occurred.
702
703 @b wxSTREAM_WRITE_ERROR
704
705 A generic error occurred on the last write call.
706
707 @b wxSTREAM_READ_ERROR
708
709 A generic error occurred on the last read call.
710 */
711 wxStreamError GetLastError() const;
712
713 /**
714 Returns the length of the stream in bytes. If the length cannot be determined
715 (this is always the case for socket streams for example), returns
716 @c wxInvalidOffset.
717
718 @since 2.5.4
719 */
720 wxFileOffset GetLength() const;
721
722 /**
723 GetLength()
724 This function returns the size of the stream. For example, for a file it is the
725 size of the file.
726 */
727 size_t GetSize() const;
728
729 /**
730 Returns @true if no error occurred on the stream.
731
732 @see GetLastError()
733 */
734 virtual bool IsOk() const;
735
736 /**
737 Returns @true if the streams supports seeking to arbitrary offsets.
738 */
739 bool IsSeekable() const;
740
741 /**
742 Internal function. It is called when the stream wants to read data of the
743 specified size. It should return the size that was actually read.
744 */
745 size_t OnSysRead(void* buffer, size_t bufsize);
746
747 /**
748 Internal function. It is called when the stream needs to change the
749 current position.
750 */
751 off_t OnSysSeek(off_t pos, wxSeekMode mode);
752
753 /**
754 Internal function. Is is called when the stream needs to know the
755 real position.
756 */
757 off_t OnSysTell() const;
758
759 /**
760 See OnSysRead().
761 */
762 size_t OnSysWrite(const void* buffer, size_t bufsize);
763 };
764