x3dio::Stream Class Reference

Interface to implement to read and write some file (regular file, HTTP, FTP, etc.). More...

#include <io.h>

Inheritance diagram for x3dio::Stream:

[legend]List of all members.


Public Member Functions
virtual bool	Append (const char *name)=0
	Open a file in order to append data to it.
virtual bool	Close ()=0
	Close an I/O stream.
virtual bool	Create (const char *name)=0
	Create an output file.
virtual bool	IsOpen (void) const =0
	Check whether a stream is open and can be used for reading and/or writing.
virtual bool	Open (const char *name)=0
	Open an input file.
virtual int	Read (void *buf, size_t size)=0
	Read size bytes from the stream.
virtual int	Seek (long offset, int whence)=0
	Move the stream pointer.
virtual bool	Update (const char *name, bool create=true)=0
	Open a file for update.
virtual int	Write (const void *buf, size_t size)=0
	Write size bytes of buf to the stream.
virtual	~Stream ()
	The stream destructor needs to be defined since it is virtual.

Detailed Description

Interface to implement to read and write some file (regular file, HTTP, FTP, etc.).

The Stream is an interface which is expected to be implemented by different objects to read and write in local files or files available over a network.

Some streams may only be able to read files (i.e. an HTTP server may only accept GET commandes), and others may only be able to write files (i.e. a serial connection to a printer)

If it is not possible to read from a stream, then the Open() and Update() function should return false:

 bool MyStream::Open(const char *name)
 {
        return false;
 }

Similarly, a stream which cannot write needs to implement the Append(), Update() and Create() functions with a simple return false statement:

 bool MyStream::Create(const char *name)
 {
        return false;
 }

A stream which can be used to read a file needs to implement the Read() function.

A stream which can be used to write a file needs to implement the Write() function.

Any stream may implement the Seek(). It is suggested that you do so if the underlaying implementation supports it. If the underlaying implementation does not support the Seek() instruction, then the user can connect it to a CacheStream to keep a local version of the file. (still to be implemented... 8-)

Constructor & Destructor Documentation

x3dio::Stream::~Stream ( ) [virtual]

The stream destructor needs to be defined since it is virtual.
Cleans up the stream class. Since this is just an interface, it does nothing.

Member Function Documentation

bool x3dio::Stream::Append ( const char * name ) [pure virtual]

Open a file in order to append data to it.
Open a file for update, but force all writes at the end of the file (i.e. fopen(name, "ab")). It will be created if it does not exist yet. You will only be able to write to the file. The file pointer will always be at the end.

Attention:
If the stream was in the open state, then it will call Close() before to try opening the new file. Then if it fails, IsOpen() will return false.

Returns:
true when the file could be opened

See also:
Open() Create() Update() Close()

Implemented in x3dio::FileStream.

bool x3dio::Stream::Close ( ) [pure virtual]

Close an I/O stream.
This function will close the file/device which the I/O stream is connected to. The file cannot be accessed again afterward.
You can close the same stream multiple times. It will really be closed the first time though. Also, only the first time will the function return true (since afterward it will already be closed.)

Returns:
true if the file is closed properly, false otherwise

See also:
Open() Create() Update() Append()

Implemented in x3dio::FileStream.

bool x3dio::Stream::Create ( const char * name ) [pure virtual]

Create an output file.
This function creates a file for writing (i.e. fopen(name, "wb");). When it works, you can then Write() to the file.

Attention:
If the stream was in the open state, then it will call Close() before to try opening the new file. Then if it fails, IsOpen() will return false.

Returns:
true when the file was successfully created.

See also:
Open() Append() Update() Close()

Implemented in x3dio::FileStream.

bool x3dio::Stream::IsOpen ( void ) const [pure virtual]

Check whether a stream is open and can be used for reading and/or writing.
This function returns true if the Read() and Write() functions can be used on the stream. Note that it does not tell you in which mode the stream was opened. Thus, one of reading or writing may fail when this function returns true.

Returns:
true if the stream is currently open

Implemented in x3dio::FileStream.

bool x3dio::Stream::Open ( const char * name ) [pure virtual]

Open an input file.
This function open a file for reading (i.e. fopen(name, "rb");). When it works, you can then Read() to the file. The file must already exist.

Attention:
If the stream was in the open state, then it will call Close() before to try opening the new file. Then if it fails, IsOpen() will return false.

Returns:
true when the file was successfully opened.

See also:
Append() Create() Update() Close()

Implemented in x3dio::FileStream.

int x3dio::Stream::Read ( void * buf,

size_t size

) [pure virtual]

Read size bytes from the stream.
This function will read up to size byte and put them in buf. The function can return less than size bytes (usually happens at the end of a file or when a network connection is slow and the incoming buffer is never full).
If the function returns zero (0), the caller will assume that it reached the end of the file. If no data is available, you should instead return an error. Some I/O implementation may be smart enough to wait and try again later. The implementation of the Stream may want to do that though (using a select(2) call).
If an error occurs, the function must return -1 unless some data is available in which case it is authorized to at least return what is available and err on the next call.

Attention:
The file needs to have been opened for reading (i.e. Open())
The implementation has to return -1 and errno set to EBADF if the Read() function is used when the stream is not open.

Returns:
count of the number of bytes read
0 when the end of the file is reached
-1 when an error occurs

See also:
Open() Close() Seek()

Implemented in x3dio::FileStream.

int x3dio::Stream::Seek ( long offset,

int whence

) [pure virtual]

Move the stream pointer.
The function moves the stream pointer using offset and whence to compute the new position. whence is the same as fseek():

SEEK_SET - use offset as the new offset

SEEK_END - use file size minus offset as the new offset

SEEK_CUR - use the current position plus offset as the new offset

The function returns the new position if possible (i.e. ftell()). When the stream is a network connection, the stream may return an error if it decides not to support seeking (i.e. no caching and thus no turning back).

Attention:
The implementation has to return -1 and errno set to EBADF if the Seek() function is used when the stream is not open.

Returns:
position when the seek worked, can be 0 for empty files -1 when an error occured

See also:
Read() Write()

Implemented in x3dio::FileStream.

bool x3dio::Stream::Update ( const char * name,

bool create = true

) [pure virtual]

Open a file for update.
Open a file to read and write into (i.e. fopen(name, "r+b")). The file needs to already exists or the function will fail unless you set the create flag to true.
The file pointer will be set to zero (i.e. at the beginning of the file).

Attention:
If the stream was in the open state, then it will call Close() before to try opening the new file. Then if it fails, IsOpen() will return false.

Returns:
true when the function succeeds

See also:
Open() Create() Append() Close()

Implemented in x3dio::FileStream.

int x3dio::Stream::Write ( const void * buf,

size_t size

) [pure virtual]

Write size bytes of buf to the stream.
This function tries to write size bytes to the stream.

Attention:
The stream needs to be opened for writing (i.e. Create()).
The implementation has to return -1 and errno set to EBADF if the Write() function is used when the stream is not open.

See also:
Read() Create() Update() Append() Seek()

Implemented in x3dio::FileStream.

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

x3dio::Stream Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation