Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revised and fixed some typos

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55781 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-09-21 22:35:10 +00:00
parent 0d2f4076e0
commit c977fa847c
1 changed files with 289 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

441
interface/wx/stream.h
View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: stream.h // Name: stream.h
// Purpose: interface of wxCountingOutputStream // Purpose: interface of wxStreamBase and its derived classes
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -10,20 +10,13 @@
@class wxCountingOutputStream @class wxCountingOutputStream
wxCountingOutputStream is a specialized output stream which does not write any wxCountingOutputStream is a specialized output stream which does not write any
data anywhere, data anywhere, instead it counts how many bytes would get written if this were a
instead it counts how many bytes would get written if this were a normal normal stream. This can sometimes be useful or required if some data gets
stream. This serialized to a stream or compressed by using stream compression and thus the
can sometimes be useful or required if some data gets serialized to a stream or final size of the stream cannot be known other than pretending to write the stream.
compressed One case where the resulting size would have to be known is if the data has
by using stream compression and thus the final size of the stream cannot be to be written to a piece of memory and the memory has to be allocated before
known other writing to it (which is probably always the case when writing to a memory stream).
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} @library{wxbase}
@category{streams} @category{streams}
@@ -53,7 +46,7 @@ public:
@class wxBufferedInputStream @class wxBufferedInputStream
This stream acts as a cache. It caches the bytes read from the specified 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. 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 This class may not be used without some other stream to read the data
from (such as a file stream or a memory stream). from (such as a file stream or a memory stream).
@@ -66,7 +59,17 @@ public:
class wxBufferedInputStream : public wxFilterInputStream class wxBufferedInputStream : public wxFilterInputStream
{ {
public: 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 @class wxStreamBuffer
@todo WRITE A DESCRIPTION
@library{wxbase} @library{wxbase}
@category{streams} @category{streams}
@@ -83,7 +87,47 @@ public:
class wxStreamBuffer class wxStreamBuffer
{ {
public: 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 Constructor. It initializes the stream buffer with the data of the specified
stream buffer. The new stream buffer has the same attributes, size, position 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) 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 stream. It is advised to use this feature only in very local area of the
program. program.
@see @ref setbufferio() wxStreamBuffer:SetBufferIO
*/ */
wxStreamBuffer(wxStreamBase& stream, BufMode mode);
wxStreamBuffer(BufMode mode);
wxStreamBuffer(const wxStreamBuffer& buffer); wxStreamBuffer(const wxStreamBuffer& buffer);
//@}
/** /**
Destructor. It finalizes all IO calls and frees all internal buffers if Destructor.
necessary. It finalizes all IO calls and frees all internal buffers if necessary.
*/ */
wxStreamBuffer(); wxStreamBuffer();
@@ -114,8 +153,8 @@ public:
/** /**
Toggles the fixed flag. Usually this flag is toggled at the same time as 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 @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 (when it has the @true value) the stream buffer to resize dynamically the
buffer. IO buffer.
@see SetBufferIO() @see SetBufferIO()
*/ */
@@ -127,8 +166,8 @@ public:
bool FlushBuffer(); bool FlushBuffer();
/** /**
Toggles the flushable flag. If @a flushable is disabled, no data are sent Toggles the flushable flag.
to the parent stream. If @a flushable is disabled, no data are sent to the parent stream.
*/ */
void Flushable(bool flushable); void Flushable(bool flushable);
@@ -153,7 +192,10 @@ public:
void* GetBufferStart() const; 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() @see Read()
*/ */
@@ -177,21 +219,33 @@ public:
/** /**
Puts a single char to the stream buffer. Puts a single char to the stream buffer.
@warning
You aren't directly notified if an error occurred during the IO call.
@see Read() @see Read()
*/ */
void PutChar(char c); void PutChar(char c);
//@{
/** /**
Copies data to @e buffer. The function returns when @a buffer is full or when Reads a block of the specified size and stores the data in buffer.
there isn't 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. any more data in the current buffer.
@see Write() @see Write()
*/ */
size_t Read(void* buffer, size_t size);
Return value size_t Read(wxStreamBuffer* buffer); Return value size_t Read(wxStreamBuffer* buffer);
//@}
/** /**
Resets to the initial state variables concerning the buffer. Resets to the initial state variables concerning the buffer.
@@ -200,45 +254,55 @@ public:
/** /**
Changes the current position. Changes the current position.
@a mode may be one of the following: Parameter @a mode may be one of the following:
@b wxFromStart - @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.
The position is counted from the start 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.
@b wxFromEnd
The position is counted from the end of the stream.
@return Upon successful completion, it returns the new offset as @return Upon successful completion, it returns the new offset as
measured in bytes from the beginning of the stream. measured in bytes from the beginning of the stream.
Otherwise, it returns wxInvalidOffset. Otherwise, it returns wxInvalidOffset.
*/ */
off_t Seek(off_t pos, wxSeekMode mode); off_t Seek(off_t pos, wxSeekMode mode);
//@{ /**
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).
@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.
@see wxStreamBuffer(), Fixed(), Flushable()
*/
void SetBufferIO(char* buffer_start, char* buffer_end);
/** /**
Destroys or invalidates the previous IO buffer and allocates a new one of the Destroys or invalidates the previous IO buffer and allocates a new one of the
specified size. specified size.
@warning
All previous pointers aren't valid anymore.
@remarks
The created IO buffer is growable by the object.
@see Fixed(), Flushable() @see Fixed(), Flushable()
*/ */
void SetBufferIO(char* buffer_start, char* buffer_end);
Remarks See also
wxStreamBuffer constructor
wxStreamBuffer::Fixed
wxStreamBuffer::Flushable
void SetBufferIO(size_t bufsize); void SetBufferIO(size_t bufsize);
//@}
/** /**
Sets the current position (in bytes) in the stream buffer. 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); void SetIntPosition(size_t pos);
@@ -254,24 +318,28 @@ public:
the stream. the stream.
@return Returns the current position in the stream if possible, @return Returns the current position in the stream if possible,
wxInvalidOffset in the other case. wxInvalidOffset in the other case.
*/ */
off_t Tell() const; off_t Tell() const;
/** /**
Truncates the buffer to the current position. 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(); void Truncate();
//@{ /**
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(). See Read().
*/ */
size_t Write(const void* buffer, size_t size);
size_t Write(wxStreamBuffer* buffer); size_t Write(wxStreamBuffer* buffer);
//@}
}; };
@@ -298,9 +366,10 @@ public:
~wxOutputStream(); ~wxOutputStream();
/** /**
Closes the stream, returning @false if an error occurs. The Closes the stream, returning @false if an error occurs.
stream is closed implicitly in the destructor if Close() is not The stream is closed implicitly in the destructor if Close() is not
called explicitly. called explicitly.
If this stream wraps another stream or some other resource such 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 as a file, then the underlying resource is closed too if it is owned
by this stream, or left open otherwise. by this stream, or left open otherwise.
@@ -308,9 +377,9 @@ public:
bool Close(); bool Close();
/** /**
Returns the number of bytes written during the last Returns the number of bytes written during the last Write().
Write(). It may return 0 even if there is no It may return 0 even if there is no error on the stream if it is
error on the stream if it is only temporarily impossible to write to it. only temporarily impossible to write to it.
*/ */
size_t LastWrite() const; size_t LastWrite() const;
@@ -337,18 +406,39 @@ public:
*/ */
off_t TellO() const; 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 Reads data from the specified input stream and stores them
in the current stream. The data is read until an error is raised in the current stream. The data is read until an error is raised
by one of the two streams. by one of the two streams.
*/ */
wxOutputStream Write(const void* buffer, size_t size);
wxOutputStream Write(wxInputStream& stream_in); 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 @class wxFilterClassFactory
@@ -365,16 +455,16 @@ public:
stream = factory-NewStream(new wxFFileInputStream(filename)); stream = factory-NewStream(new wxFFileInputStream(filename));
@endcode @endcode
wxFilterClassFactory::Find can also search wxFilterClassFactory::Find can also search for a factory by MIME type,
for a factory by MIME type, HTTP encoding or by wxFileSystem protocol. HTTP encoding or by wxFileSystem protocol.
The available factories can be enumerated The available factories can be enumerated using wxFilterClassFactory::GetFirst()
using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext". and wxFilterClassFactory::GetNext().
@library{wxbase} @library{wxbase}
@category{FIXME} @category{streams}
@see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
overview_wxarc "Archive formats such as zip" @ref overview_archive
*/ */
class wxFilterClassFactory : public wxObject class wxFilterClassFactory : public wxObject
{ {
@@ -382,7 +472,8 @@ public:
/** /**
Returns @true if this factory can handle the given protocol, MIME type, HTTP Returns @true if this factory can handle the given protocol, MIME type, HTTP
encoding or file extension. 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. can be a complete filename rather than just an extension.
*/ */
bool CanHandle(const wxString& protocol, bool CanHandle(const wxString& protocol,
@@ -390,10 +481,11 @@ public:
/** /**
A static member that finds a factory that can handle a given protocol, MIME 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 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 if found, or @NULL otherwise.
factory. It does not give away ownership of the factory.
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. can be a complete filename rather than just an extension.
*/ */
static const wxFilterClassFactory* Find(const wxString& protocol, static const wxFilterClassFactory* Find(const wxString& protocol,
@@ -404,6 +496,16 @@ public:
GetFirst and GetNext can be used to enumerate the available factories. GetFirst and GetNext can be used to enumerate the available factories.
For example, to list them: 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 GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
are available. They do not give away ownership of the factory. 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 Returns the wxFileSystem protocol supported by this factory.
to wxString(*GetProtcols()). Equivalent to @code wxString(*GetProtocols()) @endcode.
*/ */
wxString GetProtocol() const; wxString GetProtocol() const;
/** /**
Returns the protocols, MIME types, HTTP encodings or file extensions Returns the protocols, MIME types, HTTP encodings or file extensions
supported by this factory, as an array of null terminated strings. It does supported by this factory, as an array of null terminated strings.
not give away ownership of the array or strings. It does not give away ownership of the array or strings.
For example, to list the file extensions a factory supports: 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; const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
//@{ //@{
/** /**
Create a new input or output stream to decompress or compress a given stream. 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 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. takes ownership of it. If it is passed by reference then it does not.
*/ */
wxFilterInputStream* NewStream(wxInputStream& stream) const; wxFilterInputStream* NewStream(wxInputStream& stream) const;
const wxFilterOutputStream* NewStream(wxOutputStream& stream) const; wxFilterOutputStream* NewStream(wxOutputStream& stream) const;
const wxFilterInputStream* NewStream(wxInputStream* stream) const; wxFilterInputStream* NewStream(wxInputStream* stream) const;
const wxFilterOutputStream* NewStream(wxOutputStream* stream) const; wxFilterOutputStream* NewStream(wxOutputStream* stream) const;
//@} //@}
/** /**
@@ -444,23 +556,25 @@ public:
wxString PopExtension(const wxString& location) const; wxString PopExtension(const wxString& location) const;
/** /**
Adds this class factory to the list returned Adds this class factory to the list returned by GetFirst()/GetNext().
by @ref getfirst() GetFirst()/GetNext.
It is not necessary to do this to use the filter streams. It is usually It is not necessary to do this to use the filter streams. It is usually
used when implementing streams, typically the implementation will used when implementing streams, typically the implementation will
add a static instance of its factory class. add a static instance of its factory class.
It can also be used to change the order of a factory already in the list, 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 bringing it to the front. This isn't a thread safe operation so can't be
so can't be done when other threads are running that will be using the list. done when other threads are running that will be using the list.
The list does not take ownership of the factory. The list does not take ownership of the factory.
*/ */
void PushFront(); void PushFront();
/** /**
Removes this class factory from the list returned Removes this class factory from the list returned by GetFirst()/GetNext().
by @ref getfirst() GetFirst()/GetNext. Removing from the list isn't a thread safe operation so can't be done
Removing from the list isn't a thread safe operation when other threads are running that will be using the list.
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. The list does not own the factories, so removing a factory does not delete it.
*/ */
void Remove(); void Remove();
@@ -471,10 +585,13 @@ public:
/** /**
@class wxFilterOutputStream @class wxFilterOutputStream
A filter stream has the capability of a normal A filter stream has the capability of a normal stream but it can be placed
stream but it can be placed on top of another stream. So, for example, it on top of another stream. So, for example, it can compress, encrypt the data
can compress, encrypt the data which are passed to it and write them to another which are passed to it and write them to another stream.
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} @library{wxbase}
@category{streams} @category{streams}
@@ -487,6 +604,7 @@ public:
//@{ //@{
/** /**
Initializes a "filter" stream. Initializes a "filter" stream.
If the parent stream is passed as a pointer then the new 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. takes ownership of it. If it is passed by reference then it does not.
*/ */
@@ -501,10 +619,12 @@ public:
@class wxFilterInputStream @class wxFilterInputStream
A filter stream has the capability of a normal stream but it can be placed on A filter stream has the capability of a normal stream but it can be placed on
top top of another stream. So, for example, it can uncompress or decrypt the data which
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.
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} @library{wxbase}
@category{streams} @category{streams}
@@ -517,6 +637,7 @@ public:
//@{ //@{
/** /**
Initializes a "filter" stream. Initializes a "filter" stream.
If the parent stream is passed as a pointer then the new 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. takes ownership of it. If it is passed by reference then it does not.
*/ */
@@ -531,9 +652,8 @@ public:
@class wxBufferedOutputStream @class wxBufferedOutputStream
This stream acts as a cache. It caches the bytes to be written to the specified This stream acts as a cache. It caches the bytes to be written to the specified
output stream (See wxFilterOutputStream). The output stream (See wxFilterOutputStream). The data is only written when the
data is only written when the cache is full, when the buffered stream is cache is full, when the buffered stream is destroyed or when calling SeekO().
destroyed or when calling SeekO().
This class may not be used without some other stream to write the data This class may not be used without some other stream to write the data
to (such as a file stream or a memory stream). to (such as a file stream or a memory stream).
@@ -548,8 +668,7 @@ class wxBufferedOutputStream : public wxFilterOutputStream
public: public:
/** /**
Creates a buffered stream using a buffer of a default size of 1024 bytes for Creates a buffered stream using a buffer of a default size of 1024 bytes for
cashing cashing the stream @a parent.
the stream @e parent.
*/ */
wxBufferedOutputStream(const wxOutputStream& parent); wxBufferedOutputStream(const wxOutputStream& parent);
@@ -620,20 +739,25 @@ public:
*/ */
char Peek(); 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. 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 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 @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); wxInputStream& Read(wxOutputStream& stream_out);
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);
//@}
/** /**
Changes the stream current position. Changes the stream current position.
@@ -652,24 +776,49 @@ public:
*/ */
off_t TellI() const; 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 This function acts like the previous one except that it takes only one
character: it is sometimes shorter to use than the generic function. 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); 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 @class wxStreamBase
This class is the base class of most stream related classes in wxWidgets. It This class is the base class of most stream related classes in wxWidgets.
must It must not be used directly.
not be used directly.
@library{wxbase} @library{wxbase}
@category{streams} @category{streams}
@@ -691,38 +840,26 @@ public:
/** /**
This function returns the last error. 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; wxStreamError GetLastError() const;
/** /**
Returns the length of the stream in bytes. If the length cannot be determined Returns the length of the stream in bytes. If the length cannot be
(this is always the case for socket streams for example), returns determined (this is always the case for socket streams for example),
@c wxInvalidOffset. returns @c wxInvalidOffset.
@since 2.5.4 @since 2.5.4
*/ */
wxFileOffset GetLength() const; wxFileOffset GetLength() const;
/** /**
GetLength() This function returns the size of the stream.
This function returns the size of the stream. For example, for a file it is the For example, for a file it is the size of the file.
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; size_t GetSize() const;
@@ -745,14 +882,14 @@ public:
size_t OnSysRead(void* buffer, size_t bufsize); size_t OnSysRead(void* buffer, size_t bufsize);
/** /**
Internal function. It is called when the stream needs to change the Internal function.
current position. It is called when the stream needs to change the current position.
*/ */
off_t OnSysSeek(off_t pos, wxSeekMode mode); off_t OnSysSeek(off_t pos, wxSeekMode mode);
/** /**
Internal function. Is is called when the stream needs to know the Internal function.
real position. It is called when the stream needs to know the real position.
*/ */
off_t OnSysTell() const; off_t OnSysTell() const;