Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IReader_writer_base Class Referenceabstract

Base interface for readers and writers. More...

Inheritance diagram for mi::neuraylib::IReader_writer_base:
mi::base::Interface_declare< 0x919370c2, 0x2bb4, 0x40db, 0x81, 0xff, 0xd3, 0x1c, 0x52, 0x10, 0x54, 0x64 > mi::base::IInterface mi::base::Interface_declare< 0x0e6ecfbc, 0x78c3, 0x4082, 0xba, 0x51, 0xa3, 0x60, 0xbb, 0x1d, 0x6f, 0xc0, neuraylib::IReader_writer_base > mi::base::Interface_declare< 0xc03de0cf, 0x5a03, 0x4e8f, 0xa1, 0x59, 0x6c, 0xad, 0xd6, 0xf8, 0xae, 0x58, neuraylib::IReader_writer_base > mi::neuraylib::IWriter mi::neuraylib::IReader

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. Returns NULL if get_error_number() returns 0. More...
 
virtual bool eof () const =0
 Returns true if the end of the file has been reached. The result is undefined before reading or writing for the first time. 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_positiontell_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. Based on random access, this is a fast operation. More...
 
virtual bool seek_end ()=0
 Sets the stream position to the end of the file. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x919370c2, 0x2bb4, 0x40db, 0x81, 0xff, 0xd3, 0x1c, 0x52, 0x10, 0x54, 0x64 >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
IInterface
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x919370c2, 0x2bb4, 0x40db, 0x81, 0xff, 0xd3, 0x1c, 0x52, 0x10, 0x54, 0x64 >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. 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. Note: On 32 bit machines, all mi::Sint64 sizes are limited to 32 bits and thus file sizes to 4 GB.

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

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.