3c4f71cc3d
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52634 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
775 lines
20 KiB
Objective-C
775 lines
20 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: stream.h
|
|
// Purpose: interface of wxCountingOutputStream
|
|
// Author: wxWidgets team
|
|
// RCS-ID: $Id$
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxCountingOutputStream
|
|
@wxheader{stream.h}
|
|
|
|
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}
|
|
*/
|
|
class wxCountingOutputStream : public wxOutputStream
|
|
{
|
|
public:
|
|
/**
|
|
Creates a wxCountingOutputStream object.
|
|
*/
|
|
wxCountingOutputStream();
|
|
|
|
/**
|
|
Destructor.
|
|
*/
|
|
~wxCountingOutputStream();
|
|
|
|
/**
|
|
Returns the current size of the stream.
|
|
*/
|
|
size_t GetSize() const;
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxBufferedInputStream
|
|
@wxheader{stream.h}
|
|
|
|
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, wxInputStream, wxBufferedOutputStream
|
|
*/
|
|
class wxBufferedInputStream : public wxFilterInputStream
|
|
{
|
|
public:
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxStreamBuffer
|
|
@wxheader{stream.h}
|
|
|
|
|
|
@library{wxbase}
|
|
@category{streams}
|
|
|
|
@see wxStreamBase
|
|
*/
|
|
class wxStreamBuffer
|
|
{
|
|
public:
|
|
//@{
|
|
/**
|
|
Constructor. It initializes the stream buffer with the data of the specified
|
|
stream buffer. The new stream buffer has the same attributes, size, position
|
|
and they share the same buffer. This will cause problems if the stream to
|
|
which the stream buffer belong is destroyed and the newly cloned stream
|
|
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.
|
|
*/
|
|
wxStreamBuffer();
|
|
|
|
/**
|
|
Fill the IO buffer.
|
|
*/
|
|
bool FillBuffer();
|
|
|
|
/**
|
|
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.
|
|
|
|
@see SetBufferIO()
|
|
*/
|
|
void Fixed(bool fixed);
|
|
|
|
/**
|
|
Flushes the IO buffer.
|
|
*/
|
|
bool FlushBuffer();
|
|
|
|
/**
|
|
Toggles the flushable flag. If @a flushable is disabled, no data are sent
|
|
to the parent stream.
|
|
*/
|
|
void Flushable(bool flushable);
|
|
|
|
/**
|
|
Returns a pointer on the end of the stream buffer.
|
|
*/
|
|
void* GetBufferEnd() const;
|
|
|
|
/**
|
|
Returns a pointer on the current position of the stream buffer.
|
|
*/
|
|
void* GetBufferPos() const;
|
|
|
|
/**
|
|
Returns the size of the buffer.
|
|
*/
|
|
size_t GetBufferSize() const;
|
|
|
|
/**
|
|
Returns a pointer on the start of the stream buffer.
|
|
*/
|
|
void* GetBufferStart() const;
|
|
|
|
/**
|
|
Gets a single char from the stream buffer. It acts like the Read call.
|
|
|
|
@see Read()
|
|
*/
|
|
char GetChar();
|
|
|
|
/**
|
|
Returns the amount of available data in the buffer.
|
|
*/
|
|
size_t GetDataLeft();
|
|
|
|
/**
|
|
Returns the current position (counted in bytes) in the stream buffer.
|
|
*/
|
|
off_t GetIntPosition() const;
|
|
|
|
/**
|
|
Returns the amount of bytes read during the last IO call to the parent stream.
|
|
*/
|
|
size_t GetLastAccess() const;
|
|
|
|
/**
|
|
Puts a single char to the stream buffer.
|
|
|
|
@see Read()
|
|
*/
|
|
void PutChar(char c);
|
|
|
|
//@{
|
|
/**
|
|
Copies data to @e 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.
|
|
*/
|
|
void ResetBuffer();
|
|
|
|
/**
|
|
Changes the current position.
|
|
@a mode may be one of the following:
|
|
|
|
@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.
|
|
|
|
@returns 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);
|
|
|
|
//@{
|
|
/**
|
|
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
|
|
|
|
wxStreamBuffer::Fixed
|
|
|
|
wxStreamBuffer::Flushable
|
|
void SetBufferIO(size_t bufsize);
|
|
//@}
|
|
|
|
/**
|
|
Sets the current position (in bytes) in the stream buffer.
|
|
*/
|
|
void SetIntPosition(size_t pos);
|
|
|
|
/**
|
|
Returns the parent stream of the stream buffer.
|
|
*/
|
|
wxStreamBase* Stream();
|
|
|
|
/**
|
|
Gets the current position in the stream. This position is calculated from
|
|
the @e real position in the stream and from the internal buffer position: so
|
|
it gives you the position in the @e real stream counted from the start of
|
|
the stream.
|
|
|
|
@returns Returns the current position in the stream if possible,
|
|
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.
|
|
*/
|
|
void Truncate();
|
|
|
|
//@{
|
|
/**
|
|
See Read().
|
|
*/
|
|
size_t Write(const void* buffer, size_t size);
|
|
size_t Write(wxStreamBuffer* buffer);
|
|
//@}
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxOutputStream
|
|
@wxheader{stream.h}
|
|
|
|
wxOutputStream is an abstract base class which may not be used directly.
|
|
|
|
@library{wxbase}
|
|
@category{streams}
|
|
*/
|
|
class wxOutputStream : public wxStreamBase
|
|
{
|
|
public:
|
|
/**
|
|
Creates a dummy wxOutputStream object.
|
|
*/
|
|
wxOutputStream();
|
|
|
|
/**
|
|
Destructor.
|
|
*/
|
|
~wxOutputStream();
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
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.
|
|
*/
|
|
size_t LastWrite() const;
|
|
|
|
/**
|
|
Puts the specified character in the output queue and increments the
|
|
stream position.
|
|
*/
|
|
void PutC(char c);
|
|
|
|
/**
|
|
Changes the stream current position.
|
|
|
|
@param pos
|
|
Offset to seek to.
|
|
@param mode
|
|
One of wxFromStart, wxFromEnd, wxFromCurrent.
|
|
|
|
@returns The new stream position or wxInvalidOffset on error.
|
|
*/
|
|
off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart);
|
|
|
|
/**
|
|
Returns the current stream position.
|
|
*/
|
|
off_t TellO() const;
|
|
|
|
//@{
|
|
/**
|
|
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);
|
|
//@}
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxFilterClassFactory
|
|
@wxheader{stream.h}
|
|
|
|
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 @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext".
|
|
|
|
@library{wxbase}
|
|
@category{FIXME}
|
|
|
|
@see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref
|
|
overview_wxarc "Archive formats such as zip"
|
|
*/
|
|
class wxFilterClassFactory : public wxObject
|
|
{
|
|
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
|
|
can be a complete filename rather than just an extension.
|
|
*/
|
|
bool CanHandle(const wxString& protocol,
|
|
wxStreamProtocolType type = wxSTREAM_PROTOCOL) 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.
|
|
When using 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,
|
|
wxStreamProtocolType type = wxSTREAM_PROTOCOL);
|
|
|
|
//@{
|
|
/**
|
|
GetFirst and GetNext can be used to enumerate the available factories.
|
|
For example, to list them:
|
|
|
|
GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
|
|
are available. They do not give away ownership of the factory.
|
|
*/
|
|
static const wxFilterClassFactory* GetFirst() const;
|
|
const wxFilterClassFactory* GetNext() const;
|
|
//@}
|
|
|
|
/**
|
|
Returns the wxFileSystem protocol supported by this factory. Equivalent
|
|
to wxString(*GetProtcols()).
|
|
*/
|
|
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.
|
|
For example, to list the file extensions a factory supports:
|
|
*/
|
|
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;
|
|
//@}
|
|
|
|
/**
|
|
Remove the file extension of @a location if it is one of the file
|
|
extensions handled by this factory.
|
|
*/
|
|
wxString PopExtension(const wxString& location) const;
|
|
|
|
/**
|
|
Adds this class factory to the list returned
|
|
by @ref getfirst() 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.
|
|
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.
|
|
The list does not own the factories, so removing a factory does not delete it.
|
|
*/
|
|
void Remove();
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxFilterOutputStream
|
|
@wxheader{stream.h}
|
|
|
|
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.
|
|
|
|
@library{wxbase}
|
|
@category{streams}
|
|
|
|
@see wxFilterClassFactory, wxFilterInputStream
|
|
*/
|
|
class wxFilterOutputStream : public wxOutputStream
|
|
{
|
|
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 wxFilterInputStream
|
|
@wxheader{stream.h}
|
|
|
|
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.
|
|
|
|
@library{wxbase}
|
|
@category{streams}
|
|
|
|
@see wxFilterClassFactory, wxFilterOutputStream
|
|
*/
|
|
class wxFilterInputStream : public wxInputStream
|
|
{
|
|
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.
|
|
*/
|
|
wxFilterInputStream(wxInputStream& stream);
|
|
wxFilterInputStream(wxInputStream* stream);
|
|
//@}
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxBufferedOutputStream
|
|
@wxheader{stream.h}
|
|
|
|
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().
|
|
|
|
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:
|
|
/**
|
|
Creates a buffered stream using a buffer of a default size of 1024 bytes for
|
|
cashing
|
|
the stream @e parent.
|
|
*/
|
|
wxBufferedOutputStream(const wxOutputStream& parent);
|
|
|
|
/**
|
|
Destructor. Calls Sync() and destroys the internal buffer.
|
|
*/
|
|
~wxBufferedOutputStream();
|
|
|
|
/**
|
|
Calls Sync() and changes the stream position.
|
|
*/
|
|
off_t SeekO(off_t pos, wxSeekMode mode);
|
|
|
|
/**
|
|
Flushes the buffer and calls Sync() on the parent stream.
|
|
*/
|
|
void Sync();
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxInputStream
|
|
@wxheader{stream.h}
|
|
|
|
wxInputStream is an abstract base class which may not be used directly.
|
|
|
|
@library{wxbase}
|
|
@category{streams}
|
|
*/
|
|
class wxInputStream : public wxStreamBase
|
|
{
|
|
public:
|
|
/**
|
|
Creates a dummy input stream.
|
|
*/
|
|
wxInputStream();
|
|
|
|
/**
|
|
Destructor.
|
|
*/
|
|
~wxInputStream();
|
|
|
|
/**
|
|
Returns @true if some data is available in the stream right now, so that
|
|
calling Read() wouldn't block.
|
|
*/
|
|
bool CanRead() const;
|
|
|
|
/**
|
|
Returns @true after an attempt has been made to read past the end of the
|
|
stream.
|
|
*/
|
|
bool Eof() const;
|
|
|
|
/**
|
|
Returns the first character in the input queue and removes it,
|
|
blocking until it appears if necessary.
|
|
*/
|
|
char GetC();
|
|
|
|
/**
|
|
Returns the last number of bytes read.
|
|
*/
|
|
size_t LastRead() const;
|
|
|
|
/**
|
|
Returns the first character in the input queue without removing it.
|
|
*/
|
|
char Peek();
|
|
|
|
//@{
|
|
/**
|
|
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.
|
|
|
|
@returns 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);
|
|
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.
|
|
|
|
@param pos
|
|
Offset to seek to.
|
|
@param mode
|
|
One of wxFromStart, wxFromEnd, wxFromCurrent.
|
|
|
|
@returns The new stream position or wxInvalidOffset on error.
|
|
*/
|
|
off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart);
|
|
|
|
/**
|
|
Returns the current stream position.
|
|
*/
|
|
off_t TellI() const;
|
|
|
|
//@{
|
|
/**
|
|
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);
|
|
//@}
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxStreamBase
|
|
@wxheader{stream.h}
|
|
|
|
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 wxStreamBase
|
|
{
|
|
public:
|
|
/**
|
|
Creates a dummy stream object. It doesn't do anything.
|
|
*/
|
|
wxStreamBase();
|
|
|
|
/**
|
|
Destructor.
|
|
*/
|
|
~wxStreamBase();
|
|
|
|
/**
|
|
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.
|
|
|
|
@wxsince{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.
|
|
*/
|
|
size_t GetSize() const;
|
|
|
|
/**
|
|
Returns @true if no error occurred on the stream.
|
|
|
|
@see GetLastError()
|
|
*/
|
|
virtual bool IsOk() const;
|
|
|
|
/**
|
|
Returns @true if the streams supports seeking to arbitrary offsets.
|
|
*/
|
|
bool IsSeekable() const;
|
|
|
|
/**
|
|
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);
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
off_t OnSysTell() const;
|
|
|
|
/**
|
|
See OnSysRead().
|
|
*/
|
|
size_t OnSysWrite(const void* buffer, size_t bufsize);
|
|
};
|
|
|