]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/stream.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / stream.h
... / ...
CommitLineData
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*/
13enum 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*/
32class wxStreamBase
33{
34public:
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
111protected:
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*/
149class wxStreamBuffer
150{
151public:
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*/
465class wxOutputStream : public wxStreamBase
466{
467public:
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
553protected:
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*/
579class wxInputStream : public wxStreamBase
580{
581public:
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
710protected:
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*/
741class wxCountingOutputStream : public wxOutputStream
742{
743public:
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*/
777class wxBufferedInputStream : public wxFilterInputStream
778{
779public:
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*/
821enum 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*/
855class wxFilterClassFactory : public wxObject
856{
857public:
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*/
987class wxFilterOutputStream : public wxOutputStream
988{
989public:
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*/
1020class wxFilterInputStream : public wxInputStream
1021{
1022public:
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*/
1052class wxBufferedOutputStream : public wxFilterOutputStream
1053{
1054public:
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*/
1118class wxWrapperInputStream : public wxFilterInputStream
1119{
1120public:
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
1132protected:
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};