From c977fa847c49b28aef4f8881660bad0775401763 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 21 Sep 2008 22:35:10 +0000 Subject: [PATCH] revised and fixed some typos git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55781 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/stream.h | 439 +++++++++++++++++++++++++++--------------- 1 file changed, 288 insertions(+), 151 deletions(-) diff --git a/interface/wx/stream.h b/interface/wx/stream.h index ef45d4a113..d452e2fe54 100644 --- a/interface/wx/stream.h +++ b/interface/wx/stream.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: stream.h -// Purpose: interface of wxCountingOutputStream +// Purpose: interface of wxStreamBase and its derived classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,20 +10,13 @@ @class wxCountingOutputStream 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). + 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} @@ -53,7 +46,7 @@ public: @class wxBufferedInputStream This stream acts as a cache. It caches the bytes read from the specified - input stream (See wxFilterInputStream). + 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). @@ -66,7 +59,17 @@ public: class wxBufferedInputStream : public wxFilterInputStream { public: + /** + Constructor. + If a non @NULL buffer is given to the stream, it will be deleted by it. + */ + wxBufferedInputStream(wxInputStream& stream, + wxStreamBuffer *buffer = NULL); + /** + Destructor. + */ + virtual ~wxBufferedInputStream(); }; @@ -74,6 +77,7 @@ public: /** @class wxStreamBuffer + @todo WRITE A DESCRIPTION @library{wxbase} @category{streams} @@ -83,7 +87,47 @@ public: class wxStreamBuffer { public: - //@{ + + /** + Constructor, creates a new stream buffer using @a stream as a parent stream + and mode as the IO mode. + + @param stream + The parent stream. + @param mode + Can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read_write. + + One stream can have many stream buffers but only one is used internally + to pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()), + but you can call directly wxStreamBuffer::Read without any problems. + Note that all errors and messages linked to the stream are stored in the + stream, not the stream buffers: + + @code + streambuffer.Read(...); + streambuffer2.Read(...); // This call erases previous error messages set by 'streambuffer' + @endcode + + @see SetBufferIO() + */ + wxStreamBuffer(wxStreamBase& stream, BufMode mode); + + /** + Constructor; creates a new empty stream buffer which won't flush any data + to a stream. mode specifies the type of the buffer (read, write, read_write). + This stream buffer has the advantage to be stream independent and to work + only on memory buffers but it is still compatible with the rest of the + wxStream classes. You can write, read to this special stream and it will + grow (if it is allowed by the user) its internal buffer. + Briefly, it has all functionality of a "normal" stream. + + @warning + The "read_write" mode doesn't currently work for standalone stream buffers. + + @see SetBufferIO() + */ + wxStreamBuffer(BufMode mode); + /** Constructor. It initializes the stream buffer with the data of the specified stream buffer. The new stream buffer has the same attributes, size, position @@ -92,17 +136,12 @@ public: buffer continues to be used, trying to call functions in the (destroyed) stream. It is advised to use this feature only in very local area of the program. - - @see @ref setbufferio() wxStreamBuffer:SetBufferIO */ - wxStreamBuffer(wxStreamBase& stream, BufMode mode); - wxStreamBuffer(BufMode mode); wxStreamBuffer(const wxStreamBuffer& buffer); - //@} /** - Destructor. It finalizes all IO calls and frees all internal buffers if - necessary. + Destructor. + It finalizes all IO calls and frees all internal buffers if necessary. */ wxStreamBuffer(); @@ -114,8 +153,8 @@ public: /** Toggles the fixed flag. Usually this flag is toggled at the same time as @e flushable. This flag allows (when it has the @false value) or forbids - (when it has the @true value) the stream buffer to resize dynamically the IO - buffer. + (when it has the @true value) the stream buffer to resize dynamically the + IO buffer. @see SetBufferIO() */ @@ -127,8 +166,8 @@ public: bool FlushBuffer(); /** - Toggles the flushable flag. If @a flushable is disabled, no data are sent - to the parent stream. + Toggles the flushable flag. + If @a flushable is disabled, no data are sent to the parent stream. */ void Flushable(bool flushable); @@ -153,7 +192,10 @@ public: void* GetBufferStart() const; /** - Gets a single char from the stream buffer. It acts like the Read call. + Gets a single char from the stream buffer. It acts like the Read() call. + + @warning + You aren't directly notified if an error occurred during the IO call. @see Read() */ @@ -177,21 +219,33 @@ public: /** Puts a single char to the stream buffer. + @warning + You aren't directly notified if an error occurred during the IO call. + @see Read() */ void PutChar(char c); - //@{ /** - Copies data to @e buffer. The function returns when @a buffer is full or when - there isn't + Reads a block of the specified size and stores the data in buffer. + This function tries to read from the buffer first and if more data has + been requested, reads more data from the associated stream and updates + the buffer accordingly until all requested data is read. + + @return It returns the size of the data read. If the returned size is + different of the specified size, an error has occurred and + should be tested using GetLastError(). + */ + size_t Read(void* buffer, size_t size); + + /** + Copies data to @a buffer. + The function returns when @a buffer is full or when there isn't any more data in the current buffer. @see Write() */ - size_t Read(void* buffer, size_t size); Return value size_t Read(wxStreamBuffer* buffer); - //@} /** Resets to the initial state variables concerning the buffer. @@ -200,45 +254,55 @@ public: /** Changes the current position. - @a mode may be one of the following: - - @b wxFromStart + Parameter @a mode may be one of the following: - The position is counted from the start of the stream. + - @b wxFromStart: The position is counted from the start of the stream. + - @b wxFromCurrent: The position is counted from the current position of the stream. + - @b wxFromEnd: The position is counted from the end of the stream. - @b wxFromCurrent - - The position is counted from the current position of the stream. + @return Upon successful completion, it returns the new offset as + measured in bytes from the beginning of the stream. + Otherwise, it returns wxInvalidOffset. + */ + off_t Seek(off_t pos, wxSeekMode mode); - @b wxFromEnd + /** + Specifies which pointers to use for stream buffering. + You need to pass a pointer on the start of the buffer end and another + on the end. The object will use this buffer to cache stream data. + It may be used also as a source/destination buffer when you create an + empty stream buffer (See wxStreamBuffer::wxStreamBuffer). - The position is counted from the end of the stream. + @remarks + When you use this function, you will have to destroy the IO buffers + yourself after the stream buffer is destroyed or don't use it anymore. + In the case you use it with an empty buffer, the stream buffer will not + resize it when it is full. - @return Upon successful completion, it returns the new offset as - measured in bytes from the beginning of the stream. - Otherwise, it returns wxInvalidOffset. + @see wxStreamBuffer(), Fixed(), Flushable() */ - off_t Seek(off_t pos, wxSeekMode mode); + void SetBufferIO(char* buffer_start, char* buffer_end); - //@{ /** Destroys or invalidates the previous IO buffer and allocates a new one of the specified size. - @see Fixed(), Flushable() - */ - void SetBufferIO(char* buffer_start, char* buffer_end); - Remarks See also - wxStreamBuffer constructor + @warning + All previous pointers aren't valid anymore. - wxStreamBuffer::Fixed + @remarks + The created IO buffer is growable by the object. - wxStreamBuffer::Flushable + @see Fixed(), Flushable() + */ void SetBufferIO(size_t bufsize); - //@} /** Sets the current position (in bytes) in the stream buffer. + + @warning + Since it is a very low-level function, there is no check on the position: + specifying an invalid position can induce unexpected results. */ void SetIntPosition(size_t pos); @@ -254,24 +318,28 @@ public: the stream. @return Returns the current position in the stream if possible, - wxInvalidOffset in the other case. + wxInvalidOffset in the other case. */ off_t Tell() const; /** Truncates the buffer to the current position. - Note: Truncate() cannot be used to enlarge the buffer. This is - usually not needed since the buffer expands automatically. + + @note Truncate() cannot be used to enlarge the buffer. This is + usually not needed since the buffer expands automatically. */ void Truncate(); - //@{ /** - See Read(). + Writes a block of the specified size using data of buffer. + The data are cached in a buffer before being sent in one block to the stream. */ size_t Write(const void* buffer, size_t size); + + /** + See Read(). + */ size_t Write(wxStreamBuffer* buffer); - //@} }; @@ -298,9 +366,10 @@ public: ~wxOutputStream(); /** - Closes the stream, returning @false if an error occurs. The - stream is closed implicitly in the destructor if Close() is not + Closes the stream, returning @false if an error occurs. + The stream is closed implicitly in the destructor if Close() is not called explicitly. + If this stream wraps another stream or some other resource such as a file, then the underlying resource is closed too if it is owned by this stream, or left open otherwise. @@ -308,9 +377,9 @@ public: bool Close(); /** - Returns the number of bytes written during the last - Write(). It may return 0 even if there is no - error on the stream if it is only temporarily impossible to write to it. + Returns the number of bytes written during the last Write(). + It may return 0 even if there is no error on the stream if it is + only temporarily impossible to write to it. */ size_t LastWrite() const; @@ -337,18 +406,39 @@ public: */ off_t TellO() const; - //@{ + /** + Writes up to the specified amount of bytes using the data of buffer. + Note that not all data can always be written so you must check the number + of bytes really written to the stream using LastWrite() when this function + returns. + + In some cases (for example a write end of a pipe which is currently full) + it is even possible that there is no errors and zero bytes have been written. + 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); + /** Reads data from the specified input stream and stores them in the current stream. The data is read until an error is raised by one of the two streams. */ - wxOutputStream Write(const void* buffer, size_t size); wxOutputStream Write(wxInputStream& stream_in); - //@} }; +/** + 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 wxFilterClassFactory @@ -365,16 +455,16 @@ public: 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 @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext". + 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{FIXME} + @category{streams} - @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref - overview_wxarc "Archive formats such as zip" + @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, + @ref overview_archive */ class wxFilterClassFactory : public wxObject { @@ -382,7 +472,8 @@ public: /** Returns @true if this factory can handle the given protocol, MIME type, HTTP encoding or file extension. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter + + When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter can be a complete filename rather than just an extension. */ bool CanHandle(const wxString& protocol, @@ -390,10 +481,11 @@ public: /** 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 wxSTREAM_FILEEXT for the second parameter, the first parameter + 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. */ static const wxFilterClassFactory* Find(const wxString& protocol, @@ -404,6 +496,16 @@ public: 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. */ @@ -412,29 +514,39 @@ public: //@} /** - Returns the wxFileSystem protocol supported by this factory. Equivalent - to wxString(*GetProtcols()). + Returns the wxFileSystem protocol supported by this factory. + Equivalent to @code wxString(*GetProtocols()) @endcode. */ wxString GetProtocol() 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. + 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; + + for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++) + list << *p << _T("\n"); + @endcode */ const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; //@{ /** 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. */ - wxFilterInputStream* NewStream(wxInputStream& stream) const; - const wxFilterOutputStream* NewStream(wxOutputStream& stream) const; - const wxFilterInputStream* NewStream(wxInputStream* stream) const; - const wxFilterOutputStream* NewStream(wxOutputStream* stream) const; + wxFilterInputStream* NewStream(wxInputStream& stream) const; + wxFilterOutputStream* NewStream(wxOutputStream& stream) const; + wxFilterInputStream* NewStream(wxInputStream* stream) const; + wxFilterOutputStream* NewStream(wxOutputStream* stream) const; //@} /** @@ -444,23 +556,25 @@ public: wxString PopExtension(const wxString& location) const; /** - Adds this class factory to the list returned - by @ref getfirst() GetFirst()/GetNext. + 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. + 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. + 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. */ void PushFront(); /** - Removes this class factory from the list returned - by @ref getfirst() 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. + 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. */ void Remove(); @@ -471,10 +585,13 @@ public: /** @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. + 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} @@ -487,6 +604,7 @@ 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. */ @@ -501,10 +619,12 @@ public: @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. + 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} @@ -517,6 +637,7 @@ 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. */ @@ -531,9 +652,8 @@ public: @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(). + output stream (See wxFilterOutputStream). The data is only written when the + cache is full, when the buffered stream is destroyed or when calling SeekO(). This class may not be used without some other stream to write the data to (such as a file stream or a memory stream). @@ -548,8 +668,7 @@ class wxBufferedOutputStream : public wxFilterOutputStream public: /** Creates a buffered stream using a buffer of a default size of 1024 bytes for - cashing - the stream @e parent. + cashing the stream @a parent. */ wxBufferedOutputStream(const wxOutputStream& parent); @@ -620,20 +739,25 @@ public: */ char Peek(); - //@{ + /** + Reads the specified amount of bytes and stores the data in buffer. + + @warning + The buffer absolutely needs to have at least the specified size. + + @return This function returns a reference on the current object, so the + user can test any states of the stream right away. + */ + wxInputStream Read(void* buffer, size_t size); + /** 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. @return This function returns a reference on the current object, so the - user can test any states of the stream right away. + user can test any states of the stream right away. */ - wxInputStream Read(void* buffer, size_t size); - Warning Return value - This function returns a reference on the current object, so the user can test - any states of the stream right away. - wxInputStream& Read(wxOutputStream& stream_out); - //@} + wxInputStream& Read(wxOutputStream& stream_out); /** Changes the stream current position. @@ -652,24 +776,49 @@ public: */ off_t TellI() 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. + + 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 char* buffer, size_t size); + /** This function acts like the previous one except that it takes only one character: it is sometimes shorter to use than the generic function. */ - size_t Ungetch(const char* buffer, size_t size); Return value bool Ungetch(char c); - //@} }; +/** + 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. +}; /** @class wxStreamBase - This class is the base class of most stream related classes in wxWidgets. It - must - not be used directly. + This class is the base class of most stream related classes in wxWidgets. + It must not be used directly. @library{wxbase} @category{streams} @@ -691,38 +840,26 @@ public: /** This function returns the last error. - - @b wxSTREAM_NO_ERROR - - No error occurred. - - @b wxSTREAM_EOF - - An End-Of-File occurred. - - @b wxSTREAM_WRITE_ERROR - - A generic error occurred on the last write call. - - @b wxSTREAM_READ_ERROR - - A generic error occurred on the last read call. */ 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. + 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 */ wxFileOffset GetLength() const; /** - GetLength() - This function returns the size of the stream. For example, for a file it is the - size of the file. + This function returns the size of the stream. + For example, for a file it is the size of the file. + + @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. */ size_t GetSize() const; @@ -745,14 +882,14 @@ public: size_t OnSysRead(void* buffer, size_t bufsize); /** - Internal function. It is called when the stream needs to change the - current position. + Internal function. + It is called when the stream needs to change the current position. */ off_t OnSysSeek(off_t pos, wxSeekMode mode); /** - Internal function. Is is called when the stream needs to know the - real position. + Internal function. + It is called when the stream needs to know the real position. */ off_t OnSysTell() const; -- 2.45.2