x3dio::FileStream Class Reference

An implementation of the Stream interface to work with standard local files (FILE *). More...

#include <io.h>

Inheritance diagram for x3dio::FileStream:

[legend]Collaboration diagram for x3dio::FileStream:

[legend]List of all members.


Public Member Functions
virtual bool	Append (const char *name)
bool	Attach (FILE *file, bool manage=true)
	Attach a FILE * to a FileStream.
virtual bool	Close ()
	Close an I/O stream.
virtual bool	Create (const char *name)
	FileStream ()
	Initializes a FileStream.
virtual bool	IsOpen (void) const
	Check whether a stream is open and can be used for reading and/or writing.
virtual bool	Open (const char *name)
virtual int	Read (void *buf, size_t size)
	Read size bytes from the stream.
virtual int	Seek (long offset, int whence)
	Move the stream pointer.
virtual bool	Update (const char *name, bool create=true)
virtual int	Write (const void *buf, size_t size)
	Write size bytes of buf to the stream.
virtual	~FileStream ()
	Cleans up a FileStream.
Private Attributes
FILE *	f_file
bool	f_manage

Detailed Description

An implementation of the Stream interface to work with standard local files (FILE *).

The FileStream is an implementation of the Stream interface using the local file system (fopen(), fclose(), etc.)

You can Attach() standard FILE * to the stream (such as stdin and stdout) if you wish.

Note that a standard file will be seekable, but many other types of files are not (i.e. a serial device.)

In order to use this class, instantiate an object either on your stack or with new. Then open a file with Open(), Create(), Update(), Append() or Attach(). Finally, Read() or Write() in the file.

 char buf[1024];
 x3dio::FileStream my_file;
 my_file.Open("lots-of-secrets.txt");
 size = my_file.Read(buf, sizeof(buf));
 ...

Constructor & Destructor Documentation

x3dio::FileStream::FileStream ( )

Initializes a FileStream.
The constructor makes sure that the stream is marked as not opened (i.e. IsOpen() will return false).

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

Cleans up a FileStream.
The destructor ensures that the file is closed if marked as managed (which is the default.)

Member Function Documentation

bool x3dio::FileStream::Append ( const char * name ) [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()

See also:
Attach()

Implements x3dio::Stream.

bool x3dio::FileStream::Attach ( FILE * file,

bool manage = true

)

Attach a FILE * to a FileStream.
This function can be used to attach a file to a FileStream object. This is useful if you want to use pre-opened files such as stdin and stdout.
Set the manage flag to false if you do not want the FileStream to close the file for you. This is certainly very important if the file is stdin, stdout or stderr because some other function will probably be expected to close these streams.

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

bool x3dio::FileStream::Close ( ) [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()

Implements x3dio::Stream.

bool x3dio::FileStream::Create ( const char * name ) [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()

See also:
Attach()

Implements x3dio::Stream.

bool x3dio::FileStream::IsOpen ( void ) const [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

Implements x3dio::Stream.

bool x3dio::FileStream::Open ( const char * name ) [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()

See also:
Attach()

Implements x3dio::Stream.

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

size_t size

) [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()

Implements x3dio::Stream.

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

int whence

) [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()

Implements x3dio::Stream.

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

bool create = true

) [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()

See also:
Attach()

Implements x3dio::Stream.

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

size_t size

) [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()

Implements x3dio::Stream.

Member Data Documentation

FILE* x3dio::FileStream::f_file [private]

bool x3dio::FileStream::f_manage [private]

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

x3dio::FileStream Class Reference

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation