#include <stream.h>

Detailed Description

Offers an abstract interface for read/write access to a sequence of bytes.

Base class for all classes which need to provide a read/write interface to data, like a FileStream, a MemoryStream, etc...

Stream objects can be accessed directly, or through stream reader and writer classes, which offer specific read/writing interfaces to streams.

Copyright: (C) 2006 Radon Labs GmbH (C) 2013-2020 Individual contributors, see AUTHORS file

Inherits Core::RefCounted.

Inherited by IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

Public Types
enum	AccessMode { ReadAccess , WriteAccess , AppendAccess , ReadWriteAccess }
	access modes More...

enum	AccessPattern { Random , Sequential }
	access prefered pattern More...

enum	SeekOrigin { Begin , Current , End }
	seek origins More...

typedef int64_t	Position
	typedefs

typedef int64_t	Offset

typedef int64_t	Size

Public Member Functions
	Stream ()
	constructor

virtual	~Stream ()
	destructor

void	SetURI (const URI &u)
	set stream location as URI

const URI &	GetURI () const
	get stream URI

virtual bool	CanRead () const
	return true if the stream supports reading

virtual bool	CanWrite () const
	return true if the stream supports writing

virtual bool	CanSeek () const
	return true if the stream supports seeking

virtual bool	CanBeMapped () const
	return true if the stream provides direct memory access

virtual void	SetSize (Size s)
	set a new size for the stream

virtual Size	GetSize () const
	get the size of the stream in bytes

virtual Position	GetPosition () const
	get the current position of the read/write cursor

void	SetAccessMode (AccessMode m)
	set the access mode of the stream (default is ReadAccess)

AccessMode	GetAccessMode () const
	get the access mode of the stream

void	SetAccessPattern (AccessPattern p)
	set the prefered access pattern (default is Sequential)

AccessPattern	GetAccessPattern () const
	get the prefered access pattern

void	SetMediaType (const MediaType &t)
	set optional media type of stream content

const MediaType &	GetMediaType () const
	get optional media type

virtual bool	Open ()
	open the stream

virtual void	Close ()
	close the stream

bool	IsOpen () const
	return true if currently open

virtual void	Write (const void *ptr, Size numBytes)
	directly write to the stream

virtual Size	Read (void *ptr, Size numBytes)
	directly read from the stream

virtual void	Seek (Offset offset, SeekOrigin origin)
	seek in stream

virtual void	Flush ()
	flush unsaved data

virtual bool	Eof () const
	return true if end-of-stream reached

virtual void *	Map ()
	map stream to memory

virtual void	Unmap ()
	unmap stream

virtual void *	MemoryMap ()
	memory map stream to memory

virtual void	MemoryUnmap ()
	unmap memory stream

bool	IsMapped () const
	return true if stream is currently mapped to memory

Public Member Functions inherited from Core::RefCounted
	RefCounted ()
	constructor

int	GetRefCount () const
	get the current refcount

void	AddRef ()
	increment refcount by one

void	Release ()
	decrement refcount and destroy object if refcount is zero

bool	IsInstanceOf (const Rtti &rtti) const
	return true if this object is instance of given class

bool	IsInstanceOf (const Util::String &className) const
	return true if this object is instance of given class by string

bool	IsInstanceOf (const Util::FourCC &classFourCC) const
	return true if this object is instance of given class by fourcc

bool	IsA (const Rtti &rtti) const
	return true if this object is instance of given class, or a derived class

bool	IsA (const Util::String &rttiName) const
	return true if this object is instance of given class, or a derived class, by string

bool	IsA (const Util::FourCC &rttiFourCC) const
	return true if this object is instance of given class, or a derived class, by fourcc

const Util::String &	GetClassName () const
	get the class name

Util::FourCC	GetClassFourCC () const
	get the class FourCC code

Protected Attributes
URI	uri

AccessMode	accessMode

AccessPattern	accessPattern

bool	isOpen

bool	isMapped

MediaType	mediaType

Private Member Functions
	__DeclareClass (Stream)

Additional Inherited Members
Static Public Member Functions inherited from Core::RefCounted
static void	DumpRefCountingLeaks ()
	dump refcounting leaks, call at end of application (NEBULA_DEBUG builds only!)

Protected Member Functions inherited from Core::RefCounted
virtual	~RefCounted ()
	destructor (called when refcount reaches zero)

Member Typedef Documentation

◆ Offset

int64_t IO::Stream::Offset

◆ Position

int64_t IO::Stream::Position

typedefs

◆ Size

int64_t IO::Stream::Size

Member Enumeration Documentation

◆ AccessMode

enum IO::Stream::AccessMode

access modes

Enumerator
ReadAccess
WriteAccess
AppendAccess
ReadWriteAccess

◆ AccessPattern

enum IO::Stream::AccessPattern

access prefered pattern

Enumerator
Random
Sequential

◆ SeekOrigin

enum IO::Stream::SeekOrigin

seek origins

Enumerator
Begin
Current
End

Constructor & Destructor Documentation

◆ Stream()

IO::Stream::Stream ( )

constructor

◆ ~Stream()

IO::Stream::~Stream ( )

virtual

destructor

Member Function Documentation

◆ __DeclareClass()

IO::Stream::__DeclareClass ( Stream )

private

◆ CanBeMapped()

bool IO::Stream::CanBeMapped ( ) const

virtual

return true if the stream provides direct memory access

This method must return true if the stream supports direct memory access through the Map()/Unmap() methods.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ CanRead()

bool IO::Stream::CanRead ( ) const

virtual

return true if the stream supports reading

This method must return true if the derived stream class supports reading.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ CanSeek()

bool IO::Stream::CanSeek ( ) const

virtual

return true if the stream supports seeking

This method must return true if the derived stream supports seeking.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ CanWrite()

bool IO::Stream::CanWrite ( ) const

virtual

return true if the stream supports writing

This method must return true if the derived stream class supports writing.

Reimplemented in IO::EmbeddedMemoryStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ Close()

void IO::Stream::Close ( )

virtual

close the stream

Closes the stream.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, IO::SafeFileStream, and IO::ZipFileStream.

◆ Eof()

bool IO::Stream::Eof ( ) const

virtual

return true if end-of-stream reached

Return true if the read/write cursor is at the end of the stream.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ Flush()

void IO::Stream::Flush ( )

virtual

flush unsaved data

Flush any unsaved data.

Note that unsaved data will also be flushed automatically when the stream is closed.

Reimplemented in IO::FileStream.

◆ GetAccessMode()

Stream::AccessMode IO::Stream::GetAccessMode ( ) const

get the access mode of the stream

Get the access mode of the stream.

◆ GetAccessPattern()

Stream::AccessPattern IO::Stream::GetAccessPattern ( ) const

get the prefered access pattern

Get the currently set prefered access pattern of the stream.

◆ GetMediaType()

const MediaType & IO::Stream::GetMediaType ( ) const

get optional media type

◆ GetPosition()

Stream::Position IO::Stream::GetPosition ( ) const

virtual

get the current position of the read/write cursor

This method returns the current position of the read/write cursor.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ GetSize()

Stream::Size IO::Stream::GetSize ( ) const

virtual

get the size of the stream in bytes

This method returns the size of the stream in bytes.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ GetURI()

const URI & IO::Stream::GetURI ( ) const

get stream URI

Get the URI of the stream as string.

◆ IsMapped()

bool IO::Stream::IsMapped ( ) const

return true if stream is currently mapped to memory

Returns true if the stream is currently mapped.

◆ IsOpen()

bool IO::Stream::IsOpen ( ) const

return true if currently open

Return true if the stream is currently open.

◆ Map()

void * IO::Stream::Map ( )

virtual

map stream to memory

If the stream provides memory mapping, this method will return a pointer to the beginning of the stream data in memory.

The application is free to read and write to the stream through direct memory access. Special care must be taken to not read or write past the end of the mapped data (indicated by GetSize()). The normal Read()/Write() method are not valid while the stream is mapped, also the read/write cursor position will not be updated.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ MemoryMap()

void * IO::Stream::MemoryMap ( )

virtual

memory map stream to memory

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ MemoryUnmap()

void IO::Stream::MemoryUnmap ( )

virtual

unmap memory stream

Reimplemented in IO::FileStream, and IO::ZipFileStream.

◆ Open()

bool IO::Stream::Open ( )

virtual

open the stream

Open the stream.

Only one thread may open a stream at any time. Returns true if succeeded.

Reimplemented in Http::HttpNzStream, Http::HttpStream, IO::CachedStream, IO::EmbeddedMemoryStream, IO::FileStream, IO::MemoryStream, IO::SafeFileStream, and IO::ZipFileStream.

◆ Read()

Stream::Size IO::Stream::Read	(	void *	ptr,
		Size	numBytes )

virtual

directly read from the stream

Read raw data from the stream.

For more convenient reading, attach the stream to an IO::StreamReader object. The method returns the number of bytes actually read. This method is only valid if the stream class returns true in CanRead(). Returns the number of bytes actually read from the stream, this may be less then numBytes, or 0 if end-of-stream is reached.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ Seek()

void IO::Stream::Seek	(	Offset	offset,
		SeekOrigin	origin )

virtual

seek in stream

Move the read/write cursor to a new position, returns the new position in the stream.

This method is only supported if the stream class returns true in CanSeek().

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ SetAccessMode()

void IO::Stream::SetAccessMode ( AccessMode m )

set the access mode of the stream (default is ReadAccess)

This method sets the intended access mode of the stream.

The actual behaviour depends on the implementation of the derived class. The default is ReadWrite.

◆ SetAccessPattern()

void IO::Stream::SetAccessPattern ( AccessPattern p )

set the prefered access pattern (default is Sequential)

Set the prefered access pattern of the stream.

This can be Random or Sequential. This is an optional flag to improve performance with some stream implementations. The default is sequential. The pattern cannot be changed while the stream is open.

◆ SetMediaType()

void IO::Stream::SetMediaType ( const MediaType & t )

set optional media type of stream content

◆ SetSize()

void IO::Stream::SetSize ( Size s )

virtual

set a new size for the stream

This sets a new size for the stream.

Not all streams support this method. If the new size if smaller then the existing size, the contents will be clipped.

Reimplemented in IO::MemoryStream.

◆ SetURI()

void IO::Stream::SetURI ( const URI & u )

set stream location as URI

Set the URI of the stream as string.

The URI identifies the source resource of the stream.

◆ Unmap()

void IO::Stream::Unmap ( )

virtual

unmap stream

This will unmap a memory-mapped stream.

Reimplemented in IO::CachedStream, IO::FileStream, IO::MemoryStream, and IO::ZipFileStream.

◆ Write()

void IO::Stream::Write	(	const void *	ptr,
		Size	numBytes )

virtual

directly write to the stream

Write raw data to the stream.

For more convenient writing, attach the stream to an IO::StreamWriter object. This method is only valid if the stream class returns true in CanWrite().

Reimplemented in IO::FileStream, and IO::MemoryStream.

Member Data Documentation

◆ accessMode

AccessMode IO::Stream::accessMode

protected

◆ accessPattern

AccessPattern IO::Stream::accessPattern

protected

◆ isMapped

bool IO::Stream::isMapped

protected

◆ isOpen

bool IO::Stream::isOpen

protected

◆ mediaType

MediaType IO::Stream::mediaType

protected

◆ uri

URI IO::Stream::uri

protected

The documentation for this class was generated from the following files:

/github/workspace/code/foundation/io/stream.h
/github/workspace/code/foundation/io/stream.cc

Detailed Description

Public Types

Public Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Member Typedef Documentation

◆ Offset

◆ Position

◆ Size

Member Enumeration Documentation

◆ AccessMode

◆ AccessPattern

◆ SeekOrigin

Constructor & Destructor Documentation

◆ Stream()

◆ ~Stream()

Member Function Documentation

◆ __DeclareClass()

◆ CanBeMapped()

◆ CanRead()

◆ CanSeek()

◆ CanWrite()

◆ Close()

◆ Eof()

◆ Flush()

◆ GetAccessMode()

◆ GetAccessPattern()

◆ GetMediaType()

◆ GetPosition()

◆ GetSize()

◆ GetURI()

◆ IsMapped()

◆ IsOpen()

◆ Map()

◆ MemoryMap()

◆ MemoryUnmap()

◆ Open()

◆ Read()

◆ Seek()

◆ SetAccessMode()

◆ SetAccessPattern()

◆ SetMediaType()

◆ SetSize()

◆ SetURI()

◆ Unmap()

◆ Write()

Member Data Documentation

◆ accessMode

◆ accessPattern

◆ isMapped

◆ isOpen

◆ mediaType

◆ uri