Stream Class Reference

The Stream interface can be used to implement a data source or sink. More...

Inherits Reference.

List of all members.

Public Member Functions
	~Stream ()
	Empty destructor.
virtual bool_t	open ()=0
	Opens the stream.
virtual void	close ()=0
	Closes the stream.
virtual bool_t	isOpen () const =0
	Checks whether the stream is open.
virtual bool_t	canRead () const =0
	Checks whether the stream supports reading.
virtual bool_t	canWrite () const =0
	Checks whether the stream supports writing.
virtual bool_t	canSeek () const =0
	Checks whether the stream supports seeking.
virtual bool_t	read (void *buffer, int32_t bufferSize, int32_t *totalRead)=0
	Reads data from the stream.
virtual bool_t	write (const void *buffer, int32_t dataSize)=0
	Writes data to the stream.
virtual int64_t	size () const =0
	Returns the current size of the stream.
virtual int64_t	position () const =0
	Returns the current position in the stream.
virtual bool_t	seek (int64_t position)=0
	Seeks to the specified position in the stream.
int32_t	retain () const
	The default implementation keeps a constant reference count of 1.
int32_t	release () const
	The default implementation keeps a constant reference count of 1.
int32_t	retainCount () const
	The default implementation keeps a constant reference count of 1.

---

Detailed Description

The Stream interface can be used to implement a data source or sink.

It can be used as an alternative to files when it is not convenient or possible to use files.

The default implementation of primo::Reference keeps a constant reference count of 1. This can be used when the client code is the sole owner of the implemented stream and does not need to manage it through the primo::Reference interface.

---

Member Function Documentation

virtual bool_t canRead

(

)

const [pure virtual]

Checks whether the stream supports reading.

Returns:

TRUE It is possible to read form the stream. FALSE It is not possible to read from the stream and the read method always returns FALSE.

virtual bool_t canSeek

(

)

const [pure virtual]

Checks whether the stream supports seeking.

Returns:

TRUE It is possible to seek in the stream. FALSE It is not possible to seek in the stream and the seek method always returns FALSE.

virtual bool_t canWrite

(

)

const [pure virtual]

Checks whether the stream supports writing.

Returns:

TRUE It is possible to write to the stream. FALSE It is not possible to write to the stream and the write method always returns FALSE.

virtual bool_t isOpen

(

)

const [pure virtual]

Checks whether the stream is open.

Returns:

TRUE The stream is open, FALSE the stream is closed.

virtual bool_t open

(

)

[pure virtual]

Opens the stream.

Returns:

TRUE The stream is opened successfully. FALSE An error occurred.

virtual int64_t position

(

)

const [pure virtual]

Returns the current position in the stream.

Returns:

Absolute position in stream or -1 if the stream cannot be seeked. The beginning of a seekable the stream is at position 0.

See also:

canSeek

virtual bool_t read	(	void *	buffer,
		int32_t	bufferSize,
		int32_t *	totalRead
	)		[pure virtual]

Reads data from the stream.

Parameters:

buffer	[in] A pointer to the buffer where the data shall be stored.
bufferSize	[in] Buffer size in bytes. Specifies how many bytes shall be read from the stream.
totalRead	[out] A pointer to a variable that stores the actual number of bytes read from the stream. When the number of bytes returned (totalRead) is 0 then this is considered to be the end of the stream (EOS). Reading at the end of the stream succeeds but 0 bytes are returned. The number of bytes returned (totalRead) may be less than the requested bytes (bufferSize) even before the end of the stream is reached.

Remarks:

This function should block if no data is currently available in stream but more is expected to come: from network, growing file, expandable buffer, etc. The parameter totalRead should be set to 0 only when no more data is available in stream and no more data is expected to come.

Returns:

TRUE The operation is successful. FALSE Could not read from the stream.

See also:

canRead

int32_t release

(

)

const [virtual]

The default implementation keeps a constant reference count of 1.

Returns:

1

Implements Reference.

int32_t retain

(

)

const [virtual]

The default implementation keeps a constant reference count of 1.

Returns:

1

Implements Reference.

int32_t retainCount

(

)

const [virtual]

The default implementation keeps a constant reference count of 1.

Returns:

1

Implements Reference.

virtual bool_t seek

(

int64_t

position

)

[pure virtual]

Seeks to the specified position in the stream.

Parameters:

position

[in] Specifies the absolute position from the beginning of the stream (which is at position 0).

Returns:

TRUE if successful. FALSE if there's an error.

See also:

canSeek

virtual int64_t size

(

)

const [pure virtual]

Returns the current size of the stream.

Returns:

Stream size in bytes. If the size is unknown -1 is returned.

Remarks:

The stream size may increase if more data is appended to the stream. The stream size should never decrease.

virtual bool_t write	(	const void *	buffer,
		int32_t	dataSize
	)		[pure virtual]

Writes data to the stream.

Parameters:

buffer	[in] A pointer to the data that shall be written to the stream.
dataSize	[in] Specifies how many bytes to write.

Returns:

TRUE the data has been written to the stream. FALSE an error occurred while writing to the stream.

See also:

canWrite