Base interface for readers and writers. More...

#include <ireader_writer_base.h>

Inheritance diagram for mi::neuraylib::IReader_writer_base:

[legend]

Public Member Functions
virtual Sint32	get_error_number () const =0
	Returns the error number of the last error that happened in this reader or writer, or 0 if no error occurred. More...

virtual const char *	get_error_message () const =0
	Returns the error message of the last error that happened in this reader or writer. More...

virtual bool	eof () const =0
	Returns `true` if the end of the file has been reached. More...

virtual Sint32	get_file_descriptor () const =0
	Returns the file descriptor of the stream, or -1 if it is not available. More...

Random recorded access
virtual bool	supports_recorded_access () const =0
	Returns `true` if random recorded access is supported, and `false` otherwise. More...

virtual const IStream_position *	tell_position () const =0
	Returns the current position in this stream. More...

virtual bool	seek_position (const IStream_position *stream_position)=0
	Repositions the stream to the position `stream_position`. More...

virtual bool	rewind ()=0
	Resets the stream position to the beginning. More...

Random absolute access
virtual bool	supports_absolute_access () const =0
	Returns `true` if random absolute access is supported, and `false` otherwise. More...

virtual Sint64	tell_absolute () const =0
	Returns the absolute position in bytes from the beginning of the stream beginning, or -1 if absolute access is not supported. More...

virtual bool	seek_absolute (Sint64 pos)=0
	Repositions the stream to the absolute position `pos`. More...

virtual Sint64	get_file_size () const =0
	Returns the size in bytes of the data in the stream. More...

virtual bool	seek_end ()=0
	Sets the stream position to the end of the file. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x919370c2, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x919370c2, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

Base interface for readers and writers.

Readers and writers are an abstraction of plain byte oriented data access to files or network streamed data. They separate the data access from the data parsing and formatting.

Readers and writers can have certain capabilities. The capabilities are hierarchical, meaning that if a capability is supported, all capabilities above it are supported as well. Possible capabilities are:

Streaming: The minimal capability is sequential unbuffered reading or writing of data, suitable for streaming or stdin/stdout usage.
Lookahead: Applicable to readers only, lookahead gives access to a flexible, but maybe limited amount of data in the input stream that has not been read yet. It is usually a byproduct of buffering or random access, where after reading of the lookahead the read position is reset to the position before the lookahead. It can be used for examining a file for a magic header that identifies the file format.
Random recorded access: The reader or writer is capable of jumping to a position that has previously been recorded. The recorded position uses an opaque representation of a position in a stream.
Random absolute access: The reader or writer is capable of jumping to an absolute position indexed from the beginning of the stream.

The different capabilities are not expressed in a class hierarchy but in query functions and well-defined behavior of all API functions for all capabilities.

Readers and writers are exposed as three interfaces to the importers and exporters: mi::neuraylib::IReader_writer_base (this interface), mi::neuraylib::IReader and mi::neuraylib::IWriter, where the latter two derive from the first.

Readers and writers operate in binary mode only. They do not perform any automatic conversions, for example, such as newline to CR/LF for text mode files on Windows. If you require such conversions for a specific file format, you need to add the necessary control sequences yourself and have your parser accept them correctly.

Read and write sizes, as well as seek and tell positions, are consistently mi::Sint64 types. It is a signed integer since some functions will use -1 as error indicator.

The mi::neuraylib::IReader_writer_base class deals with the common part between reader and writer classes. This includes random access functions, access to an optionally available file descriptor, and handling of error and end-of-file conditions. The file descriptor is provided to support 3rd party libraries that require a file descriptor. It may not be available for all readers/writers.

Member Function Documentation

^◆ eof()

virtual bool mi::neuraylib::IReader_writer_base::eof ( ) const

pure virtual

Returns true if the end of the file has been reached.

The result is undefined before reading or writing for the first time.

^◆ get_error_message()

virtual const char * mi::neuraylib::IReader_writer_base::get_error_message ( ) const

pure virtual

Returns the error message of the last error that happened in this reader or writer.

The returned string might be platform-dependent, e.g., by using strerror(). The method might return NULL if get_error_number() returns 0.

^◆ get_error_number()

virtual Sint32 mi::neuraylib::IReader_writer_base::get_error_number ( ) const

pure virtual

Returns the error number of the last error that happened in this reader or writer, or 0 if no error occurred.

^◆ get_file_descriptor()

virtual Sint32 mi::neuraylib::IReader_writer_base::get_file_descriptor ( ) const

pure virtual

Returns the file descriptor of the stream, or -1 if it is not available.

^◆ get_file_size()

virtual Sint64 mi::neuraylib::IReader_writer_base::get_file_size ( ) const

pure virtual

Returns the size in bytes of the data in the stream.

Based on random access, this is a fast operation.

^◆ rewind()

virtual bool mi::neuraylib::IReader_writer_base::rewind ( )

pure virtual

Resets the stream position to the beginning.

Returns: true in case of success (and clears the error condition), and false in case of errors.

^◆ seek_absolute()

virtual bool mi::neuraylib::IReader_writer_base::seek_absolute ( Sint64 pos )

pure virtual

Repositions the stream to the absolute position pos.

Returns: true in case of success, or false in case of errors, e.g., if pos is not valid or absolute access is not supported and the state of the stream remains unchanged.

^◆ seek_end()

virtual bool mi::neuraylib::IReader_writer_base::seek_end ( )

pure virtual

Sets the stream position to the end of the file.

Returns: true in case of success, or false in case of errors.

^◆ seek_position()

virtual bool mi::neuraylib::IReader_writer_base::seek_position ( const IStream_position * stream_position )

pure virtual

Repositions the stream to the position stream_position.

Returns: true in case of success, or false in case of errors, e.g., if stream_position is not valid or recorded access is not supported and the state of the stream remains unchanged.

^◆ supports_absolute_access()

virtual bool mi::neuraylib::IReader_writer_base::supports_absolute_access ( ) const

pure virtual

Returns true if random absolute access is supported, and false otherwise.

^◆ supports_recorded_access()

virtual bool mi::neuraylib::IReader_writer_base::supports_recorded_access ( ) const

pure virtual

Returns true if random recorded access is supported, and false otherwise.

^◆ tell_absolute()

virtual Sint64 mi::neuraylib::IReader_writer_base::tell_absolute ( ) const

pure virtual

Returns the absolute position in bytes from the beginning of the stream beginning, or -1 if absolute access is not supported.

^◆ tell_position()

virtual const IStream_position * mi::neuraylib::IReader_writer_base::tell_position ( ) const

pure virtual

Returns the current position in this stream.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ eof()

◆ get_error_message()

◆ get_error_number()

◆ get_file_descriptor()

◆ get_file_size()

◆ rewind()

◆ seek_absolute()

◆ seek_end()

◆ seek_position()

◆ supports_absolute_access()

◆ supports_recorded_access()

◆ tell_absolute()

◆ tell_position()

^◆ eof()

^◆ get_error_message()

^◆ get_error_number()

^◆ get_file_descriptor()

^◆ get_file_size()

^◆ rewind()

^◆ seek_absolute()

^◆ seek_end()

^◆ seek_position()

^◆ supports_absolute_access()

^◆ supports_recorded_access()

^◆ tell_absolute()

^◆ tell_position()