neuray API Programmer's Manual

mi::neuraylib::IReader_writer_base Class Reference

[Importer and Exporter]

Description

Base interface for readers and writers. Reader and writer 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.

Reader and writer 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.

Reader and Writer 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. Note: On 32 bit machines, all mi::Sint64 sizes are limited to 32 bits and thus file sizes to 4 GB.

The IReader_writer_base class deals with the common part between reader and writer classes. This includes random access functions, access to an optional available file descriptor, and handling of error and end-of-file conditions.

A file descriptor is provided to support 3rd party libraries that require a file descriptor. It may not be available for all reader/writer.

mi::base::Interface_declare\< ..., neuraylib::IReader_writer_base \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IReader_writer_base \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface. A writer supports binary block writes and string-oriented line writes that accept...A writer supports binary block writes and string-oriented line writes that accept a zero-terminated string as argument. A reader supports binary block reads and string-oriented line reads that zero-terminate...A reader supports binary block reads and string-oriented line reads that zero-terminate the result.

Public Member Functions

virtual bool  eof() const =0
Returns true if the end of the file has been reached. 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 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.
virtual Sint32 get_file_descriptor() const =0
Returns the file descriptor of the stream, or -1 if it is not available.

Random recorded access

virtual bool  rewind() =0
Resets the stream position to the beginning. More...
virtual bool  seek_position( const IStream_position* stream_position) =0
Repositions the stream to the position stream_position. More...
virtual bool  supports_recorded_access() const =0
Returns true if random recorded access is supported, and false otherwise.
virtual const IStream_position* tell_position() const =0
Returns the current position in this stream.

Random absolute access

virtual Sint64 get_file_size() const =0
Returns the size in bytes of the data in the stream. More...
virtual bool  seek_absolute( Sint64 pos) =0
Repositions the stream to the absolute position pos. More...
virtual bool  seek_end() =0
Sets the stream position to the end of the file. More...
virtual bool  supports_absolute_access() const =0
Returns true if random absolute access is supported, and false otherwise.
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.

Member Functions

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.

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. Returns NULL if get_error_number() returns 0.

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.

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.

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.

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.

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.

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.

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.

virtual bool mi::​neuraylib::​IReader_writer_base::supports_absolute_access() const [pure virtual]

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

virtual bool mi::​neuraylib::​IReader_writer_base::supports_recorded_access() const [pure virtual]

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

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.

virtual const IStream_position* mi::​neuraylib::​IReader_writer_base::tell_position() const [pure virtual]

Returns the current position in this stream.