// Purpose: interface of wxStreamBase and its derived classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+
/**
- @class wxCountingOutputStream
+ These enumeration values are returned by various functions in the context
+ of wxStream classes.
+*/
+enum wxStreamError
+{
+ wxSTREAM_NO_ERROR = 0, //!< No error occurred.
+ wxSTREAM_EOF, //!< EOF reached in Read() or similar.
+ wxSTREAM_WRITE_ERROR, //!< generic write error on the last write call.
+ wxSTREAM_READ_ERROR //!< generic read error on the last read call.
+};
- wxCountingOutputStream is a specialized output stream which does not write any
- data anywhere, instead it counts how many bytes would get written if this were a
- normal stream. This can sometimes be useful or required if some data gets
- serialized to a stream or compressed by using stream compression and thus the
- final size of the stream cannot be known other than pretending to write the stream.
- One case where the resulting size would have to be known is if the data has
- to be written to a piece of memory and the memory has to be allocated before
- writing to it (which is probably always the case when writing to a memory stream).
+/**
+ @class wxStreamBase
+
+ This class is the base class of most stream related classes in wxWidgets.
+ It must not be used directly.
@library{wxbase}
@category{streams}
+
+ @see wxStreamBuffer
*/
-class wxCountingOutputStream : public wxOutputStream
+class wxStreamBase
{
public:
/**
- Creates a wxCountingOutputStream object.
+ Creates a dummy stream object. It doesn't do anything.
*/
- wxCountingOutputStream();
+ wxStreamBase();
/**
Destructor.
*/
- virtual ~wxCountingOutputStream();
+ virtual ~wxStreamBase();
/**
- Returns the current size of the stream.
+ This function returns the last error.
*/
- size_t GetSize() const;
-};
-
+ wxStreamError GetLastError() const;
+ /**
+ Returns the length of the stream in bytes. If the length cannot be
+ determined (this is always the case for socket streams for example),
+ returns ::wxInvalidOffset.
-/**
- @class wxBufferedInputStream
+ @since 2.5.4
+ */
+ virtual wxFileOffset GetLength() const;
- This stream acts as a cache. It caches the bytes read from the specified
- input stream (see wxFilterInputStream).
- It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
- This class may not be used without some other stream to read the data
- from (such as a file stream or a memory stream).
+ /**
+ This function returns the size of the stream.
+ For example, for a file it is the size of the file.
- @library{wxbase}
- @category{streams}
+ @warning
+ There are streams which do not have size by definition, such as socket
+ streams. In that cases, GetSize() returns 0 so you should always test its
+ return value.
+ */
+ virtual size_t GetSize() const;
- @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
-*/
-class wxBufferedInputStream : public wxFilterInputStream
-{
-public:
/**
- Constructor using the provided buffer or default.
+ Returns @true if no error occurred on the stream.
- @param stream
- The associated low-level stream.
- @param buffer
- The buffer to use if non-@NULL. Notice that the ownership of this
- buffer is taken by the stream, i.e. it will delete it. If this
- parameter is @NULL a default 1KB buffer is used.
+ @see GetLastError()
*/
- wxBufferedInputStream(wxInputStream& stream,
- wxStreamBuffer *buffer = NULL);
+ virtual bool IsOk() const;
/**
- Constructor allowing to specify the size of the buffer.
+ Returns @true if the stream supports seeking to arbitrary offsets.
+ */
+ virtual bool IsSeekable() const;
- This is just a more convenient alternative to creating a wxStreamBuffer
- of the given size and using the other overloaded constructor of this
- class.
+ /**
+ Resets the stream state.
- @param stream
- The associated low-level stream.
- @param bufsize
- The size of the buffer, in bytes.
+ By default, resets the stream to good state, i.e. clears any errors.
+ Since wxWidgets 2.9.3 can be also used to explicitly set the state to
+ the specified error (the @a error argument didn't exist in the previous
+ versions).
- @since 2.9.0
+ @see GetLastError()
*/
- wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
+ void Reset(wxStreamError error = wxSTREAM_NO_ERROR);
/**
- Destructor.
+ Returns the opposite of IsOk().
+ You can use this function to test the validity of the stream as if
+ it was a pointer:
+
+ @code
+ bool DoSomething(wxInputStream& stream)
+ {
+ wxInt32 data;
+ if (!stream.Read(&data, 4))
+ return false;
+ ...
+ }
+ @endcode
*/
- virtual ~wxBufferedInputStream();
-};
+ bool operator!() const;
+
+protected:
+
+ /**
+ Internal function.
+ It is called when the stream needs to change the current position.
+
+ @param pos
+ Offset to seek to.
+ @param mode
+ One of the ::wxSeekMode enumeration values.
+
+ @return The new stream position or ::wxInvalidOffset on error.
+ */
+ virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);
+ /**
+ Internal function.
+ It is called when the stream needs to know the real position.
+ @return The current stream position.
+ */
+ virtual wxFileOffset OnSysTell() const;
+};
/**
@class wxStreamBuffer
- @todo WRITE A DESCRIPTION
+ wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
+ linked to a stream.
+
+ Each stream always has one autoinitialized stream buffer, but you may
+ attach more of them to the same stream.
@library{wxbase}
@category{streams}
- @see wxStreamBase
+ @see wxStreamBase, @ref overview_stream
*/
class wxStreamBuffer
{
@code
streambuffer.Read(...);
- streambuffer2.Read(...); // This call erases previous error messages set by 'streambuffer'
+ streambuffer2.Read(...);
+ // This call erases previous error messages set by 'streambuffer'
+ // assuming that both instances are stream buffers for the same stream
@endcode
@see SetBufferIO()
and calling SetBufferIO() but is more convenient.
@since 2.9.0
+
+ @param bufsize
+ The size of buffer in bytes.
+ @param stream
+ The associated input stream, the buffer will be used in read mode.
*/
- wxStreamBuffer(wxInputStream& stream, size_t bufsize);
+ wxStreamBuffer(size_t bufsize, wxInputStream& stream);
/**
Constructor for an output buffer of the specified size.
and calling SetBufferIO() but is more convenient.
@since 2.9.0
+
+ @param bufsize
+ The size of buffer in bytes.
+ @param stream
+ The associated output stream, the buffer will be used in write mode.
*/
- wxStreamBuffer(wxOutputStream& stream, size_t bufsize);
+ wxStreamBuffer(size_t bufsize, wxOutputStream& stream);
/**
Constructor; creates a new empty stream buffer which won't flush any data
@see Write()
*/
- Return value size_t Read(wxStreamBuffer* buffer);
+ size_t Read(wxStreamBuffer* buffer);
/**
Resets to the initial state variables concerning the buffer.
@return Upon successful completion, it returns the new offset as
measured in bytes from the beginning of the stream.
- Otherwise, it returns wxInvalidOffset.
+ Otherwise, it returns ::wxInvalidOffset.
*/
virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode);
@see wxStreamBuffer(), Fixed(), Flushable()
*/
- void SetBufferIO(char* buffer_start, char* buffer_end);
+ void SetBufferIO(void* start, void* end, bool takeOwnership = false);
/**
Destroys or invalidates the previous IO buffer and allocates a new one of the
the stream.
@return Returns the current position in the stream if possible,
- wxInvalidOffset in the other case.
+ ::wxInvalidOffset in the other case.
*/
virtual wxFileOffset Tell() const;
@class wxOutputStream
wxOutputStream is an abstract base class which may not be used directly.
+ It is the base class of all streams which provide a Write() function,
+ i.e. which can be used to output data (e.g. to a file, to a socket, etc).
+
+ If you want to create your own output stream, you'll need to derive from this
+ class and implement the protected OnSysWrite() function only.
@library{wxbase}
@category{streams}
@param mode
One of wxFromStart, wxFromEnd, wxFromCurrent.
- @return The new stream position or wxInvalidOffset on error.
+ @return The new stream position or ::wxInvalidOffset on error.
*/
virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
This function returns a reference on the current object, so the user can
test any states of the stream right away.
*/
- wxOutputStream& Write(const void* buffer, size_t size);
+ virtual wxOutputStream& Write(const void* buffer, size_t size);
/**
Reads data from the specified input stream and stores them
by one of the two streams.
*/
wxOutputStream& Write(wxInputStream& stream_in);
-};
+protected:
+ /**
+ Internal function. It is called when the stream wants to write data of the
+ specified size @a bufsize into the given @a buffer.
-/**
- Enumeration values used by wxFilterClassFactory.
-*/
-enum wxStreamProtocolType
-{
- wxSTREAM_PROTOCOL, //!< wxFileSystem protocol (should be only one).
- wxSTREAM_MIMETYPE, //!< MIME types the stream handles.
- wxSTREAM_ENCODING, //!< The HTTP Content-Encodings the stream handles.
- wxSTREAM_FILEEXT //!< File extensions the stream handles.
+ It should return the size that was actually wrote (which maybe zero if
+ @a bufsize is zero or if an error occurred; in this last case the internal
+ variable @c m_lasterror should be appropriately set).
+ */
+ size_t OnSysWrite(const void* buffer, size_t bufsize);
};
/**
- @class wxFilterClassFactory
-
- Allows the creation of filter streams to handle compression formats such
- as gzip and bzip2.
-
- For example, given a filename you can search for a factory that will
- handle it and create a stream to decompress it:
+ @class wxInputStream
- @code
- factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
- if (factory)
- stream = factory-NewStream(new wxFFileInputStream(filename));
- @endcode
+ wxInputStream is an abstract base class which may not be used directly.
+ It is the base class of all streams which provide a Read() function,
+ i.e. which can be used to read data from a source (e.g. a file, a socket, etc).
- wxFilterClassFactory::Find can also search for a factory by MIME type,
- HTTP encoding or by wxFileSystem protocol.
- The available factories can be enumerated using wxFilterClassFactory::GetFirst()
- and wxFilterClassFactory::GetNext().
+ If you want to create your own input stream, you'll need to derive from this
+ class and implement the protected OnSysRead() function only.
@library{wxbase}
@category{streams}
-
- @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
- @ref overview_archive
*/
-class wxFilterClassFactory : public wxObject
+class wxInputStream : public wxStreamBase
{
public:
/**
- Returns @true if this factory can handle the given protocol, MIME type, HTTP
- encoding or file extension.
-
- When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
- can be a complete filename rather than just an extension.
+ Creates a dummy input stream.
*/
- bool CanHandle(const wxString& protocol,
- wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
+ wxInputStream();
/**
- A static member that finds a factory that can handle a given protocol, MIME
- type, HTTP encoding or file extension. Returns a pointer to the class
- factory if found, or @NULL otherwise.
- It does not give away ownership of the factory.
-
- When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
- can be a complete filename rather than just an extension.
+ Destructor.
*/
- static const wxFilterClassFactory* Find(const wxString& protocol,
- wxStreamProtocolType type = wxSTREAM_PROTOCOL);
+ virtual ~wxInputStream();
- //@{
/**
- GetFirst and GetNext can be used to enumerate the available factories.
- For example, to list them:
-
- @code
- wxString list;
- const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
-
- while (factory) {
- list << factory->GetProtocol() << _T("\n");
- factory = factory->GetNext();
- }
- @endcode
-
- GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
- are available. They do not give away ownership of the factory.
+ Returns @true if some data is available in the stream right now, so that
+ calling Read() wouldn't block.
*/
- static const wxFilterClassFactory* GetFirst() const;
- const wxFilterClassFactory* GetNext() const;
- //@}
+ virtual bool CanRead() const;
/**
- Returns the wxFileSystem protocol supported by this factory.
- Equivalent to @code wxString(*GetProtocols()) @endcode.
+ Returns @true after an attempt has been made to read past the end of the
+ stream.
*/
- wxString GetProtocol() const;
+ virtual bool Eof() const;
/**
- Returns the protocols, MIME types, HTTP encodings or file extensions
- supported by this factory, as an array of null terminated strings.
- It does not give away ownership of the array or strings.
-
- For example, to list the file extensions a factory supports:
-
- @code
- wxString list;
- const wxChar *const *p;
+ Returns the first character in the input queue and removes it,
+ blocking until it appears if necessary.
- for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
- list << *p << _T("\n");
- @endcode
+ On success returns a value between 0 - 255; on end of file returns @c wxEOF.
*/
- virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
+ int GetC();
- //@{
/**
- Create a new input or output stream to decompress or compress a given stream.
-
- If the parent stream is passed as a pointer then the new filter stream
- takes ownership of it. If it is passed by reference then it does not.
+ Returns the last number of bytes read.
*/
- wxFilterInputStream* NewStream(wxInputStream& stream) const;
- wxFilterOutputStream* NewStream(wxOutputStream& stream) const;
- wxFilterInputStream* NewStream(wxInputStream* stream) const;
- wxFilterOutputStream* NewStream(wxOutputStream* stream) const;
- //@}
+ virtual size_t LastRead() const;
/**
- Remove the file extension of @a location if it is one of the file
- extensions handled by this factory.
+ Returns the first character in the input queue without removing it.
*/
- wxString PopExtension(const wxString& location) const;
+ virtual char Peek();
/**
- Adds this class factory to the list returned by GetFirst()/GetNext().
-
- It is not necessary to do this to use the filter streams. It is usually
- used when implementing streams, typically the implementation will
- add a static instance of its factory class.
+ Reads the specified amount of bytes and stores the data in buffer.
+ To check if the call was successful you must use LastRead() to check
+ if this call did actually read @a size bytes (if it didn't, GetLastError()
+ should return a meaningful value).
- It can also be used to change the order of a factory already in the list,
- bringing it to the front. This isn't a thread safe operation so can't be
- done when other threads are running that will be using the list.
+ @warning
+ The buffer absolutely needs to have at least the specified size.
- The list does not take ownership of the factory.
+ @return This function returns a reference on the current object, so the
+ user can test any states of the stream right away.
*/
- void PushFront();
+ virtual wxInputStream& Read(void* buffer, size_t size);
/**
- Removes this class factory from the list returned by GetFirst()/GetNext().
- Removing from the list isn't a thread safe operation so can't be done
- when other threads are running that will be using the list.
+ Reads data from the input queue and stores it in the specified output stream.
+ The data is read until an error is raised by one of the two streams.
- The list does not own the factories, so removing a factory does not delete it.
+ @return This function returns a reference on the current object, so the
+ user can test any states of the stream right away.
*/
- void Remove();
-};
+ wxInputStream& Read(wxOutputStream& stream_out);
+ /**
+ Changes the stream current position.
+ This operation in general is possible only for seekable streams
+ (see wxStreamBase::IsSeekable()); non-seekable streams support only
+ seeking positive amounts in mode @c wxFromCurrent (this is implemented
+ by reading data and simply discarding it).
-/**
- @class wxFilterOutputStream
+ @param pos
+ Offset to seek to.
+ @param mode
+ One of wxFromStart, wxFromEnd, wxFromCurrent.
- A filter stream has the capability of a normal stream but it can be placed
- on top of another stream. So, for example, it can compress, encrypt the data
- which are passed to it and write them to another stream.
+ @return The new stream position or ::wxInvalidOffset on error.
+ */
+ virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
- @note
- The use of this class is exactly the same as of wxOutputStream.
- Only a constructor differs and it is documented below.
+ /**
+ Returns the current stream position or ::wxInvalidOffset if it's not
+ available (e.g. socket streams do not have a size nor a current stream
+ position).
+ */
+ virtual wxFileOffset TellI() const;
- @library{wxbase}
- @category{streams}
+ /**
+ This function is only useful in read mode.
+ It is the manager of the "Write-Back" buffer. This buffer acts like a
+ temporary buffer where data which has to be read during the next read IO
+ call are put. This is useful when you get a big block of data which you
+ didn't want to read: you can replace them at the top of the input queue
+ by this way.
+
+ Be very careful about this call in connection with calling SeekI() on
+ the same stream. Any call to SeekI() will invalidate any previous call
+ to this method (otherwise you could SeekI() to one position, "unread" a
+ few bytes there, SeekI() to another position and data would be either
+ lost or corrupted).
+
+ @return Returns the amount of bytes saved in the Write-Back buffer.
+ */
+ size_t Ungetch(const void* buffer, size_t size);
- @see wxFilterClassFactory, wxFilterInputStream
-*/
-class wxFilterOutputStream : public wxOutputStream
-{
-public:
- //@{
/**
- Initializes a "filter" stream.
+ This function acts like the previous one except that it takes only one
+ character: it is sometimes shorter to use than the generic function.
+ */
+ bool Ungetch(char c);
- If the parent stream is passed as a pointer then the new filter stream
- takes ownership of it. If it is passed by reference then it does not.
+protected:
+
+ /**
+ Internal function. It is called when the stream wants to read data of the
+ specified size @a bufsize and wants it to be placed inside @a buffer.
+
+ It should return the size that was actually read or zero if EOF has been
+ reached or an error occurred (in this last case the internal @c m_lasterror
+ variable should be set accordingly as well).
*/
- wxFilterOutputStream(wxOutputStream& stream);
- wxFilterOutputStream(wxOutputStream* stream);
- //@}
+ size_t OnSysRead(void* buffer, size_t bufsize) = 0;
};
-/**
- @class wxFilterInputStream
- A filter stream has the capability of a normal stream but it can be placed on
- top of another stream. So, for example, it can uncompress or decrypt the data which
- are read from another stream and pass it to the requester.
+/**
+ @class wxCountingOutputStream
- @note
- The interface of this class is the same as that of wxInputStream.
- Only a constructor differs and it is documented below.
+ wxCountingOutputStream is a specialized output stream which does not write any
+ data anywhere, instead it counts how many bytes would get written if this were a
+ normal stream. This can sometimes be useful or required if some data gets
+ serialized to a stream or compressed by using stream compression and thus the
+ final size of the stream cannot be known other than pretending to write the stream.
+ One case where the resulting size would have to be known is if the data has
+ to be written to a piece of memory and the memory has to be allocated before
+ writing to it (which is probably always the case when writing to a memory stream).
@library{wxbase}
@category{streams}
-
- @see wxFilterClassFactory, wxFilterOutputStream
*/
-class wxFilterInputStream : public wxInputStream
+class wxCountingOutputStream : public wxOutputStream
{
public:
- //@{
/**
- Initializes a "filter" stream.
+ Creates a wxCountingOutputStream object.
+ */
+ wxCountingOutputStream();
- If the parent stream is passed as a pointer then the new filter stream
- takes ownership of it. If it is passed by reference then it does not.
+ /**
+ Destructor.
*/
- wxFilterInputStream(wxInputStream& stream);
- wxFilterInputStream(wxInputStream* stream);
- //@}
-};
+ virtual ~wxCountingOutputStream();
+ /**
+ Returns the current size of the stream.
+ */
+ size_t GetSize() const;
+};
/**
- @class wxBufferedOutputStream
-
- This stream acts as a cache. It caches the bytes to be written to the specified
- output stream (See wxFilterOutputStream). The data is only written when the
- cache is full, when the buffered stream is destroyed or when calling SeekO().
+ @class wxBufferedInputStream
- This class may not be used without some other stream to write the data
- to (such as a file stream or a memory stream).
+ This stream acts as a cache. It caches the bytes read from the specified
+ input stream (see wxFilterInputStream).
+ It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
+ This class may not be used without some other stream to read the data
+ from (such as a file stream or a memory stream).
@library{wxbase}
@category{streams}
- @see wxStreamBuffer, wxOutputStream
+ @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
*/
-class wxBufferedOutputStream : public wxFilterOutputStream
+class wxBufferedInputStream : public wxFilterInputStream
{
public:
/**
buffer is taken by the stream, i.e. it will delete it. If this
parameter is @NULL a default 1KB buffer is used.
*/
- wxBufferedOutputStream(wxOutputStream& stream,
- wxStreamBuffer *buffer = NULL);
+ wxBufferedInputStream(wxInputStream& stream,
+ wxStreamBuffer *buffer = NULL);
/**
Constructor allowing to specify the size of the buffer.
@since 2.9.0
*/
- wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
+ wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
/**
- Destructor. Calls Sync() and destroys the internal buffer.
+ Destructor.
*/
- virtual ~wxBufferedOutputStream();
+ virtual ~wxBufferedInputStream();
+};
- /**
- Calls Sync() and changes the stream position.
- */
- virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
- /**
- Flushes the buffer and calls Sync() on the parent stream.
- */
- virtual void Sync();
-};
+/**
+ Enumeration values used by wxFilterClassFactory.
+*/
+enum wxStreamProtocolType
+{
+ wxSTREAM_PROTOCOL, //!< wxFileSystem protocol (should be only one).
+ wxSTREAM_MIMETYPE, //!< MIME types the stream handles.
+ wxSTREAM_ENCODING, //!< The HTTP Content-Encodings the stream handles.
+ wxSTREAM_FILEEXT //!< File extensions the stream handles.
+};
/**
- @class wxInputStream
+ @class wxFilterClassFactory
- wxInputStream is an abstract base class which may not be used directly.
+ Allows the creation of filter streams to handle compression formats such
+ as gzip and bzip2.
+
+ For example, given a filename you can search for a factory that will
+ handle it and create a stream to decompress it:
+
+ @code
+ factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+ if (factory)
+ stream = factory->NewStream(new wxFFileInputStream(filename));
+ @endcode
+
+ wxFilterClassFactory::Find can also search for a factory by MIME type,
+ HTTP encoding or by wxFileSystem protocol.
+ The available factories can be enumerated using wxFilterClassFactory::GetFirst()
+ and wxFilterClassFactory::GetNext().
@library{wxbase}
@category{streams}
+
+ @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
+ @ref overview_archive
*/
-class wxInputStream : public wxStreamBase
+class wxFilterClassFactory : public wxObject
{
public:
/**
- Creates a dummy input stream.
- */
- wxInputStream();
+ Returns @true if this factory can handle the given protocol, MIME type, HTTP
+ encoding or file extension.
- /**
- Destructor.
+ When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
+ can be a complete filename rather than just an extension.
*/
- virtual ~wxInputStream();
+ bool CanHandle(const wxString& protocol,
+ wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
/**
- Returns @true if some data is available in the stream right now, so that
- calling Read() wouldn't block.
- */
- virtual bool CanRead() const;
+ A static member that finds a factory that can handle a given protocol, MIME
+ type, HTTP encoding or file extension. Returns a pointer to the class
+ factory if found, or @NULL otherwise.
+ It does not give away ownership of the factory.
- /**
- Returns @true after an attempt has been made to read past the end of the
- stream.
+ When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
+ can be a complete filename rather than just an extension.
*/
- virtual bool Eof() const;
+ static const wxFilterClassFactory* Find(const wxString& protocol,
+ wxStreamProtocolType type = wxSTREAM_PROTOCOL);
+ //@{
/**
- Returns the first character in the input queue and removes it,
- blocking until it appears if necessary.
- */
- int GetC();
+ GetFirst and GetNext can be used to enumerate the available factories.
+ For example, to list them:
- /**
- Returns the last number of bytes read.
+ @code
+ wxString list;
+ const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
+
+ while (factory) {
+ list << factory->GetProtocol() << wxT("\n");
+ factory = factory->GetNext();
+ }
+ @endcode
+
+ GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
+ are available. They do not give away ownership of the factory.
*/
- virtual size_t LastRead() const;
+ static const wxFilterClassFactory* GetFirst();
+ const wxFilterClassFactory* GetNext() const;
+ //@}
/**
- Returns the first character in the input queue without removing it.
+ Returns the wxFileSystem protocol supported by this factory.
+ Equivalent to @code wxString(*GetProtocols()) @endcode.
*/
- virtual char Peek();
+ wxString GetProtocol() const;
/**
- Reads the specified amount of bytes and stores the data in buffer.
-
- @warning
- The buffer absolutely needs to have at least the specified size.
+ Returns the protocols, MIME types, HTTP encodings or file extensions
+ supported by this factory, as an array of null terminated strings.
+ It does not give away ownership of the array or strings.
- @return This function returns a reference on the current object, so the
- user can test any states of the stream right away.
- */
- virtual wxInputStream& Read(void* buffer, size_t size);
+ For example, to list the file extensions a factory supports:
- /**
- Reads data from the input queue and stores it in the specified output stream.
- The data is read until an error is raised by one of the two streams.
+ @code
+ wxString list;
+ const wxChar *const *p;
- @return This function returns a reference on the current object, so the
- user can test any states of the stream right away.
+ for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
+ list << *p << wxT("\n");
+ @endcode
*/
- wxInputStream& Read(wxOutputStream& stream_out);
+ virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
+ //@{
/**
- Changes the stream current position.
-
- @param pos
- Offset to seek to.
- @param mode
- One of wxFromStart, wxFromEnd, wxFromCurrent.
+ Create a new input or output stream to decompress or compress a given stream.
- @return The new stream position or wxInvalidOffset on error.
+ If the parent stream is passed as a pointer then the new filter stream
+ takes ownership of it. If it is passed by reference then it does not.
*/
- virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
+ virtual wxFilterInputStream* NewStream(wxInputStream& stream) const = 0;
+ virtual wxFilterOutputStream* NewStream(wxOutputStream& stream) const = 0;
+ virtual wxFilterInputStream* NewStream(wxInputStream* stream) const = 0;
+ virtual wxFilterOutputStream* NewStream(wxOutputStream* stream) const = 0;
+ //@}
/**
- Returns the current stream position.
+ Remove the file extension of @a location if it is one of the file
+ extensions handled by this factory.
*/
- virtual wxFileOffset TellI() const;
+ wxString PopExtension(const wxString& location) const;
/**
- This function is only useful in read mode.
- It is the manager of the "Write-Back" buffer. This buffer acts like a
- temporary buffer where data which has to be read during the next read IO
- call are put. This is useful when you get a big block of data which you
- didn't want to read: you can replace them at the top of the input queue
- by this way.
+ Adds this class factory to the list returned by GetFirst()/GetNext().
- Be very careful about this call in connection with calling SeekI() on
- the same stream. Any call to SeekI() will invalidate any previous call
- to this method (otherwise you could SeekI() to one position, "unread" a
- few bytes there, SeekI() to another position and data would be either
- lost or corrupted).
+ It is not necessary to do this to use the filter streams. It is usually
+ used when implementing streams, typically the implementation will
+ add a static instance of its factory class.
- @return Returns the amount of bytes saved in the Write-Back buffer.
+ It can also be used to change the order of a factory already in the list,
+ bringing it to the front. This isn't a thread safe operation so can't be
+ done when other threads are running that will be using the list.
+
+ The list does not take ownership of the factory.
*/
- size_t Ungetch(const void* buffer, size_t size);
+ void PushFront();
/**
- This function acts like the previous one except that it takes only one
- character: it is sometimes shorter to use than the generic function.
+ Removes this class factory from the list returned by GetFirst()/GetNext().
+ Removing from the list isn't a thread safe operation so can't be done
+ when other threads are running that will be using the list.
+
+ The list does not own the factories, so removing a factory does not delete it.
*/
- bool Ungetch(char c);
+ void Remove();
};
+
/**
- These enumeration values are returned by various functions in the context
- of wxStream classes.
+ @class wxFilterOutputStream
+
+ A filter stream has the capability of a normal stream but it can be placed
+ on top of another stream. So, for example, it can compress, encrypt the data
+ which are passed to it and write them to another stream.
+
+ @note
+ The use of this class is exactly the same as of wxOutputStream.
+ Only a constructor differs and it is documented below.
+
+ @library{wxbase}
+ @category{streams}
+
+ @see wxFilterClassFactory, wxFilterInputStream
*/
-enum wxStreamError
+class wxFilterOutputStream : public wxOutputStream
{
- wxSTREAM_NO_ERROR = 0, //!< No error occurred.
- wxSTREAM_EOF, //!< EOF reached in Read() or similar.
- wxSTREAM_WRITE_ERROR, //!< generic write error on the last write call.
- wxSTREAM_READ_ERROR //!< generic read error on the last read call.
+public:
+ //@{
+ /**
+ Initializes a "filter" stream.
+
+ If the parent stream is passed as a pointer then the new filter stream
+ takes ownership of it. If it is passed by reference then it does not.
+ */
+ wxFilterOutputStream(wxOutputStream& stream);
+ wxFilterOutputStream(wxOutputStream* stream);
+ //@}
};
+
+
/**
- @class wxStreamBase
+ @class wxFilterInputStream
- This class is the base class of most stream related classes in wxWidgets.
- It must not be used directly.
+ A filter stream has the capability of a normal stream but it can be placed on
+ top of another stream. So, for example, it can uncompress or decrypt the data which
+ are read from another stream and pass it to the requester.
+
+ @note
+ The interface of this class is the same as that of wxInputStream.
+ Only a constructor differs and it is documented below.
@library{wxbase}
@category{streams}
- @see wxStreamBuffer
+ @see wxFilterClassFactory, wxFilterOutputStream
*/
-class wxStreamBase
+class wxFilterInputStream : public wxInputStream
{
public:
+ //@{
/**
- Creates a dummy stream object. It doesn't do anything.
- */
- wxStreamBase();
+ Initializes a "filter" stream.
- /**
- Destructor.
+ If the parent stream is passed as a pointer then the new filter stream
+ takes ownership of it. If it is passed by reference then it does not.
*/
- virtual ~wxStreamBase();
+ wxFilterInputStream(wxInputStream& stream);
+ wxFilterInputStream(wxInputStream* stream);
+ //@}
+};
- /**
- This function returns the last error.
- */
- wxStreamError GetLastError() const;
- /**
- Returns the length of the stream in bytes. If the length cannot be
- determined (this is always the case for socket streams for example),
- returns @c wxInvalidOffset.
- @since 2.5.4
- */
- virtual wxFileOffset GetLength() const;
+/**
+ @class wxBufferedOutputStream
- /**
- This function returns the size of the stream.
- For example, for a file it is the size of the file.
+ This stream acts as a cache. It caches the bytes to be written to the specified
+ output stream (See wxFilterOutputStream). The data is only written when the
+ cache is full, when the buffered stream is destroyed or when calling SeekO().
- @warning
- There are streams which do not have size by definition, such as socket
- streams. In that cases, GetSize returns 0 so you should always test its
- return value.
- */
- virtual size_t GetSize() const;
+ This class may not be used without some other stream to write the data
+ to (such as a file stream or a memory stream).
+
+ @library{wxbase}
+ @category{streams}
+ @see wxStreamBuffer, wxOutputStream
+*/
+class wxBufferedOutputStream : public wxFilterOutputStream
+{
+public:
/**
- Returns @true if no error occurred on the stream.
+ Constructor using the provided buffer or default.
- @see GetLastError()
+ @param stream
+ The associated low-level stream.
+ @param buffer
+ The buffer to use if non-@NULL. Notice that the ownership of this
+ buffer is taken by the stream, i.e. it will delete it. If this
+ parameter is @NULL a default 1KB buffer is used.
*/
- virtual bool IsOk() const;
+ wxBufferedOutputStream(wxOutputStream& stream,
+ wxStreamBuffer *buffer = NULL);
/**
- Returns @true if the streams supports seeking to arbitrary offsets.
- */
- virtual bool IsSeekable() const;
+ Constructor allowing to specify the size of the buffer.
- /**
- Internal function. It is called when the stream wants to read data of the
- specified size. It should return the size that was actually read.
- */
- size_t OnSysRead(void* buffer, size_t bufsize);
+ This is just a more convenient alternative to creating a wxStreamBuffer
+ of the given size and using the other overloaded constructor of this
+ class.
- /**
- See OnSysRead().
- */
- size_t OnSysWrite(const void* buffer, size_t bufsize);
+ @param stream
+ The associated low-level stream.
+ @param bufsize
+ The size of the buffer, in bytes.
+ @since 2.9.0
+ */
+ wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
-protected:
+ /**
+ Destructor. Calls Sync() and destroys the internal buffer.
+ */
+ virtual ~wxBufferedOutputStream();
/**
- Internal function.
- It is called when the stream needs to change the current position.
+ Calls Sync() and changes the stream position.
*/
- virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);
+ virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
/**
- Internal function.
- It is called when the stream needs to know the real position.
+ Flushes the buffer and calls Sync() on the parent stream.
*/
- virtual wxFileOffset OnSysTell() const;
+ virtual void Sync();
};
+
projects / wxWidgets.git / blobdiff