Cross-Platform C++

ot::io
class InputStream  (abstract)

#include "ot/io/InputStream.h"

ot::ManagedObject ot::io::BufferedInputStream ot::io::ByteArrayInputStream ot::io::FileInputStream ot::io::FilterInputStream Abstract base class with the ability to read bytes from a data source. Concrete classes derived from InputStream may be used to read bytes from a wide range of data sources including the console, a file or a network socket connection.

Unlike the standard C++ istream, this class does not concern itself with parsing or decoding, it just deals with the reading of bytes of data. In this respect it is closer to the C++ streambuf class - but avoids the complications of buffering or having an output capability.

InputStreams only concern themselves with the reading of bytes - not characters. If the application requires characters then an InputStream can be wrapped by an InputStreamReader that knows how the InputStream is encoded.

It is easy to construct your own class derived from InputStream. There are a small number of pure virtual methods for which a derived class must provide an implementation: available(), close() and read().

The following example opens an InputStream to read from a network resource and wraps it in an InputStreamReader to convert the byte stream into Unicode characters:-

    try {
        const URL url(OT_T("http://www.elcel.com"));
        RefPtr<InputStream> rpIS = url.openStream();
        // wrap the InputStream by an InputStreamReader to convert the
        // byte stream into Unicode characters
        RefPtr<Reader> rpReader(new InputStreamReader(rpIS.get());
        CharType ch;
        while( (ch = rpReader->read()) != Reader::EndOfFile) {
            Console::cout() << ch;
        }
    }
    catch(Exception& e) {
        Console::cerr() << e.toString() << endl;
    }




Method Summary
 virtual size_t available()
         Returns the number of bytes that can be read without blocking.
 virtual void close()
         Closes the InputStream.
 virtual void mark(size_t readLimit)
         Marks the current position in the byte stream.
 virtual bool markSupported() const
         Tests whether the InputStream supports the mark() operation.
 virtual int read()
         Reads and returns a single Byte or InputStream::EndOfFile.
 virtual long read(Byte* pBuffer, size_t bufLen)=0
         Reads up to bufLen bytes into the supplied buffer.
 virtual void reset()
         Resets the position in the byte stream to a previously marked position.
 virtual size_t skip(size_t n)
         Reads and discards n bytes.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Typedefs

int_type

typedef int int_type


unit_type

typedef Byte unit_type

Enumerations

enum { EndOfFile = -1}  /* End of byte stream reached */ 


Method Detail

available

virtual size_t available()
Returns the number of bytes that can be read without blocking. Some data sources (notably network socket and pipe streams) may make bytes available at a rate that is slower than the application can read them. In this case calls to read() may block until at least one byte becomes available. This method may be used to avoid making blocking calls.

Note, however, that the utility of this function is severely limited. Some sub-classes (e.g. FileInputStream) always return zero from available() and zero is also returned when the stream is at the end. For these reasons, it is rarely appropriate for an application to loop waiting for a positive return value from available().

Returns:
the number of bytes that can be read without blocking
Exceptions:
IOException - if an I/O error occurs

close

virtual void close()
Closes the InputStream. Once an InputStream is closed, all system resources associated with the stream are released, preventing any further read(), mark(), reset() or skip() operations. Further calls to close() have no effect.

Exceptions:
IOException - if an I/O error occurs.

mark

virtual void mark(size_t readLimit)
Marks the current position in the byte stream. Subsequent reset() operations will attempt to re-establish the stream's position to the marked position.

Supporting mark() implies that the InputStream must maintain an internal buffer containing all the bytes read from the point at which mark() was called. The size of this buffer is implementation dependent, but is guaranteed to hold at least readLimit bytes before it becomes full. When the buffer limit is exceeded, the marked position is automatically invalidated, with the result that subsequent reset() operations will fail.

Only one mark position is maintained by the InputStream. Further calls to mark() will establish a new mark position; reset() can only reset the position to the most recently established mark position.

Parameters:
readLimit - specifies the minimum number of bytes that the InputStream must return before making the marked position invalid.
Exceptions:
IOException - if the InputStream does not support the mark() operation.
IOException - if the InputStream is closed.
See also:
markSupported() , reset()

markSupported

virtual bool markSupported() const
Tests whether the InputStream supports the mark() operation. The base class contains an implementation that always returns false.

Returns:
true if the InputStream supports the mark() operation; false otherwise
See also:
mark() , reset()

read

virtual int read()
Reads and returns a single Byte or InputStream::EndOfFile. The return value is a signed integer. This is so that all byte values (0-255) as well as InputStream::EndOfFile (-1) can be returned.

Returns:
The Byte read or InputStream::EndOfFile if the end of the byte stream has been reached.
Exceptions:
IOException - if an error occurs while reading from the byte stream

read

virtual long read(Byte* pBuffer,
                  size_t bufLen)=0
Reads up to bufLen bytes into the supplied buffer.

Parameters:
pBuffer - A pointer to the buffer into which the bytes will be copied. This must be capable of holding at least bufLen bytes.
bufLen - The maximum number of bytes to read into the passed buffer. If this exceeds the maximum value that can be represented by a long integer, it is reduced to a value that can be so represented.
Returns:
The number of bytes read or InputStream::EndOfFile if the end of the stream has been reached.
Exceptions:
IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
IOException - if an error occurs while reading from the byte stream

reset

virtual void reset()
Resets the position in the byte stream to a previously marked position. It is permitted to call reset() multiple times. Each time it is called, the position will be reset to the position established by the most recent mark() operation.

Exceptions:
IOException - if mark() is not supported
IOException - if the InputStream is closed.
IOException - if mark() was not successfully called or the internal buffer has been exhausted (i.e. the readLimit specified in the mark() call has been exceeded)
See also:
mark()

skip

virtual size_t skip(size_t n)
Reads and discards n bytes. This is the equivalent to calling read() n times or until InputStream::EndOfFile is returned.

Parameters:
n - The number of bytes to skip.
Returns:
the number of bytes skipped.
Exceptions:
IOException - if an error occurs while reading from the byte stream


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements