OpenTop C++ class: SequenceInputStream

Overview

Namespace

Class

Glossary

Index

OpenTop Portal

OpenTop 1.5

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

Cross-Platform C++

SUMMARY: CONSTRUCTOR | METHOD

DETAIL: CONSTRUCTOR | METHOD

ot::io
class SequenceInputStream

#include "ot/io/SequenceInputStream.h"

An input stream which combines a sequence of zero or more InputStreams into one contiguous stream of bytes. The input streams held within the contained sequence are used as a source of bytes, with each stream being read until it is exhausted and returns EndOfFile, at which time it is removed from the sequence. Reading then commences with the next stream in the sequence. This process continues until all the contained input streams have been exhausted, at which time further calls to read() will return EndOfFile.

InputStreams may be added to the contained sequence until this SequenceInputStream is closed.

This class follows the OpenTop convention whereby the reference-counts for the contained InputStream objects are incremented when they are stored in the internal sequence and decremented on removal. In this way the application does not need to concern itself with maintaining the lifetime of InputStreams stored within this sequence.

Since:: OpenTop 1.5

Constructor/Destructor Summary
`SequenceInputStream()` Constructs an empty SequenceInputStream.
`SequenceInputStream(const InputStreamList& seq)` Constructs a SequenceInputStream from a passed sequence (which may be empty).
`SequenceInputStream(InputStream* pStream)` Constructs a SequenceInputStream from another InputStream.
`SequenceInputStream(InputStream* pStream1, InputStream* pStream2)` Constructs a SequenceInputStream from two InputStreams.

Method Summary
`void`	`addStream(InputStream* pStream)` Adds an InputStream to the end of the contained sequence.
`virtual size_t`	`available()` Returns the number of bytes that can be read without blocking.
`virtual void`	`close()` Closes the InputStream.
`virtual long`	`read(Byte* pBuffer, size_t bufLen)` Reads up to `bufLen` bytes into the supplied buffer.

Methods inherited from class ot::io::InputStream

mark(size_t), markSupported(), read(), reset(), skip(size_t)

Methods inherited from class ot::ManagedObject

addRef(), getRefCount(), onFinalRelease(), operator=(const ManagedObject&), release()

Typedefs

InputStreamList

typedef std::list< RefPtr< InputStream > > InputStreamList

Constructor/Destructor Detail

SequenceInputStream

 SequenceInputStream()

Constructs an empty SequenceInputStream. Before this stream is used InputStreams should be added to the internal sequence using the addStream() method.

SequenceInputStream

 SequenceInputStream(const InputStreamList& seq)

Constructs a SequenceInputStream from a passed sequence (which may be empty).

Parameters:: seq - an InputStreamList, the members of which will be copied into the internal InputStream sequence.

SequenceInputStream

 SequenceInputStream(InputStream* pStream)

Constructs a SequenceInputStream from another InputStream. Further streams may be added to the internal sequence using the addStream() method.

Parameters:: pStream - a pointer to an InputStream.

Exceptions:: NullPointerException - if pStream is null.

SequenceInputStream

 SequenceInputStream(InputStream* pStream1,
                     InputStream* pStream2)

Constructs a SequenceInputStream from two InputStreams.

Parameters:: pStream1 - a pointer to an InputStream.
pStream2 - a pointer to a second InputStream.

Exceptions:: NullPointerException - if either of pStream1 or pStream2 are null.

Method Detail

addStream

void addStream(InputStream* pStream)

Adds an InputStream to the end of the contained sequence.

Exceptions:: NullPointerException - if either of pStream is null.
IOException - if this SequenceInputStream has been closed.

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.

read

virtual long read(Byte* pBuffer,
                  size_t bufLen)

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