File Class Reference

#include <file.h>

Inherits MemoryPoolObject, and Stream.

Inherited by LocalFile, RAMFile, RAMFile, and StdFile.

Public Types
enum	access {   NONE = 0x00000000 , READ = 0x00000001 , WRITE = 0x00000002 , APPEND = 0x00000004 ,   CREATE = 0x00000008 , TRUNCATE = 0x00000010 , TEXT = 0x00000020 , BINARY = 0x00000040 ,   READWRITE = (READ | WRITE) , ONLYNEW = 0x00000080 , STREAMING = 0x00000100 , NONE = 0x00000000 ,   READ = 0x00000001 , WRITE = 0x00000002 , APPEND = 0x00000004 , CREATE = 0x00000008 ,   TRUNCATE = 0x00000010 , TEXT = 0x00000020 , BINARY = 0x00000040 , READWRITE = (READ | WRITE) ,   NEW = 0x00000080 }
enum	seekMode {   START , CURRENT , END , START ,   CURRENT , END }
enum	access {   NONE = 0x00000000 , READ = 0x00000001 , WRITE = 0x00000002 , APPEND = 0x00000004 ,   CREATE = 0x00000008 , TRUNCATE = 0x00000010 , TEXT = 0x00000020 , BINARY = 0x00000040 ,   READWRITE = (READ | WRITE) , ONLYNEW = 0x00000080 , STREAMING = 0x00000100 , NONE = 0x00000000 ,   READ = 0x00000001 , WRITE = 0x00000002 , APPEND = 0x00000004 , CREATE = 0x00000008 ,   TRUNCATE = 0x00000010 , TEXT = 0x00000020 , BINARY = 0x00000040 , READWRITE = (READ | WRITE) ,   NEW = 0x00000080 }
enum	seekMode {   START , CURRENT , END , START ,   CURRENT , END }
enum	EFileError {   FileError_None = 0 , FileError_FNF , FileError_Access , FileError_Open ,   FileError_Read , FileError_Write , FileError_Seek , FileError_Nomem ,   FileError_Fault }
Public Types inherited from Stream
enum	EStreamFrom { FromStart = 0 , FromMarker , FromEnd }

Public Member Functions
Bool	eof ()
virtual Bool	open (const Char *filename, Int access=0)
	Open a file for access.
virtual void	close (void)
	Close the file !!! File object no longer valid after this call !!!
virtual Int	read (void *buffer, Int bytes)
virtual Int	write (const void *buffer, Int bytes)
virtual Int	seek (Int bytes, seekMode mode=CURRENT)
virtual void	nextLine (Char *buf=NULL, Int bufSize=0)=0
	reads until it reaches a new-line character
virtual Bool	scanInt (Int &newInt)=0
	read an integer from the current file position.
virtual Bool	scanReal (Real &newReal)=0
	read a real number from the current file position.
virtual Bool	scanString (AsciiString &newString)=0
	read a string from the current file position.
virtual Bool	print (const Char *format,...)
	Prints formated string to text file.
virtual Int	size (void)
	Returns the size of the file.
virtual Int	position (void)
	Returns the current read/write position.
void	setName (const char *name)
	Set the name of the file.
const char *	getName (void) const
	Returns a pointer to the name of the file.
Int	getAccess (void) const
	Returns file's access flags.
void	deleteOnClose (void)
	Causes the File object to delete itself when it closes.
virtual char *	readEntireAndClose ()=0
virtual File *	convertToRAMFile ()=0
virtual Bool	open (const Char *filename, Int access=0)
	Open a file for access.
virtual void	close (void)
	Close the file !!! File object no longer valid after this call !!!
virtual Int	read (void *buffer, Int bytes)
virtual Int	write (void *buffer, Int bytes)
virtual Int	seek (Int bytes, seekMode mode=CURRENT)
virtual Bool	printf (const Char *format,...)
	Prints formated string to text file.
virtual Int	size (void)
	Returns the size of the file.
virtual Int	position (void)
	Returns the current read/write position.
void	setName (const Char *name)
	Set the name of the file.
Char *	getName (void)
	Returns a pointer to the name of the file.
Bool	getName (Char *buffer, Int max)
	Copies the name of the file to the buffer.
Int	getAccess (void)
	Returns file's access flags.
void	deleteOnClose (void)
	Causes the File object to delete itself when it closes.
	File ()
	Default constructor - Create an unassociated File.
	File (const Char *name, ERights rights=Rights_ReadOnly)
	Name constructor - Create a File with an associated name.
	File (const UString &name, ERights rights=Rights_ReadOnly)
virtual	~File ()
	Destructor.
const UString &	GetName (void) const
	Retrieve name of file.
virtual void	SetName (const UString &name)
	Associate a name to the file.
virtual ERights	GetRights (void) const
	Retrieve file access rights.
virtual void	SetRights (ERights rights)
	Set file access rights.
virtual bool	IsAvailable (bool force=false)
	Check if the file is available.
virtual bool	IsOpen (void) const
	Check if te file is open.
virtual EFileError	Open (ERights rights)
	Open the file for access.
virtual EFileError	Open (const UString &name, ERights rights)
	Open the file with the associated name for access.
virtual void	Close (void)
	Close the file.
virtual EFileError	Create (void)
	Create a new file.
virtual EFileError	Delete (void)
	Delete an existing file.
virtual EFileError	Load (void *&outBuffer, UInt32 &outSize)
	Load the file into memory.
virtual EFileError	Save (const void *buffer, UInt32 size)
	Write file data.
virtual bool	OnFileError (EFileError error, bool canRetry)
	Error handling hook.
virtual UInt32	GetLength (void)
	Get the length of the file.
virtual void	SetLength (UInt32 length)
	Set the length of the file.
virtual UInt32	GetMarker (void)
	Get file position marker.
virtual void	SetMarker (Int32 offset, EStreamFrom from)
	Set file position marker.
virtual bool	AtEnd (void)
	End of file test.
virtual UInt32	GetBytes (void *ptr, UInt32 bytes)
	Read bytes from the file.
virtual UInt32	PutBytes (const void *ptr, UInt32 bytes)
	Write bytes to the file.
virtual UInt32	PeekBytes (void *ptr, UInt32 bytes)
	Read bytes from the file without marker adjustment.
virtual void	Flush (void)
	Flush the stream.
Public Member Functions inherited from MemoryPoolObject
void	deleteInstance ()

Protected Member Functions
	File ()
	This class can only used as a base class.
	File ()
	This class can only used as a base class.
virtual	~File ()
Protected Member Functions inherited from MemoryPoolObject
virtual	~MemoryPoolObject ()
void *	operator new (size_t s)
void	operator delete (void *p)
virtual MemoryPool *	getObjectMemoryPool ()=0

Protected Attributes
AsciiString	m_nameStr
	Stores file name.
Int	m_access
	How the file was opened.
Bool	m_open
	Has the file been opened.
Bool	m_deleteOnClose
	delete File object on close()
Char	m_name [IO_MAX_PATH+1]
	Stores file name.

Friends
class	FileSystem

Detailed Description

File is an interface class for basic file operations.

All code should use the File class and not its derivatives, unless absolutely necessary. Also FS::Open should be used to create File objects and open files.

Definition at line 82 of file file.h.

Member Enumeration Documentation

access [1/2]

enum File::access

Enumerator
NONE
READ	Access file for reading.
WRITE	Access file for writing.
APPEND	Seek to end of file on open.
CREATE	Create file if it does not exist.
TRUNCATE	Delete all data in file when opened.
TEXT	Access file as text data.
BINARY	Access file as binary data.
READWRITE
ONLYNEW	Only create file if it does not exist.
STREAMING	Do not read this file into a ram file, read it as requested.
NONE
READ	Access file for reading.
WRITE	Access file for writing.
APPEND	Seek to end of file on open.
CREATE	Create file if it does not exist.
TRUNCATE	Delete all data in file when opened.
TEXT	Access file as text data.
BINARY	Access file as binary data.
READWRITE
NEW	Only create file if it does not exist.

Definition at line 90 of file file.h.

access [2/2]

enum File::access

Enumerator
NONE
READ	Access file for reading.
WRITE	Access file for writing.
APPEND	Seek to end of file on open.
CREATE	Create file if it does not exist.
TRUNCATE	Delete all data in file when opened.
TEXT	Access file as text data.
BINARY	Access file as binary data.
READWRITE
ONLYNEW	Only create file if it does not exist.
STREAMING	Do not read this file into a ram file, read it as requested.
NONE
READ	Access file for reading.
WRITE	Access file for writing.
APPEND	Seek to end of file on open.
CREATE	Create file if it does not exist.
TRUNCATE	Delete all data in file when opened.
TEXT	Access file as text data.
BINARY	Access file as binary data.
READWRITE
NEW	Only create file if it does not exist.

Definition at line 80 of file WSYS_file.h.

EFileError

enum File::EFileError

Enumerator
FileError_None
FileError_FNF
FileError_Access
FileError_Open
FileError_Read
FileError_Write
FileError_Seek
FileError_Nomem
FileError_Fault

Definition at line 50 of file File.h.

seekMode [1/2]

enum File::seekMode

Enumerator
START	Seek position is relative to start of file.
CURRENT	Seek position is relative to current file position.
END	Seek position is relative from the end of the file.
START	Seek position is relative to start of file.
CURRENT	Seek position is relative to current file position.
END	Seek position is relative from the end of the file.

Definition at line 107 of file file.h.

seekMode [2/2]

enum File::seekMode

Enumerator
START	Seek position is relative to start of file.
CURRENT	Seek position is relative to current file position.
END	Seek position is relative from the end of the file.
START	Seek position is relative to start of file.
CURRENT	Seek position is relative to current file position.
END	Seek position is relative from the end of the file.

Definition at line 94 of file WSYS_file.h.

Constructor & Destructor Documentation

File() [1/5]

File::File ( )

protected

This class can only used as a base class.

Definition at line 103 of file File.cpp.

File() [2/5]

File::File ( )

protected

This class can only used as a base class.

~File() [1/2]

File::~File ( )

protectedvirtual

Definition at line 123 of file File.cpp.

File() [3/5]

File::File

(

)

Default constructor - Create an unassociated File.

File() [4/5]

File::File	(	const Char *	name,
		ERights	rights = Rights_ReadOnly )

Name constructor - Create a File with an associated name.

Definition at line 84 of file File.cpp.

File() [5/5]

File::File	(	const UString &	name,
		ERights	rights = Rights_ReadOnly )

Definition at line 109 of file File.cpp.

~File() [2/2]

virtual File::~File ( )

virtual

Destructor.

Member Function Documentation

AtEnd()

bool File::AtEnd ( void )

virtual

End of file test.

Implements Stream.

Definition at line 923 of file File.cpp.

Close()

void File::Close ( void )

virtual

Close the file.

Definition at line 447 of file File.cpp.

close() [1/2]

void File::close ( void )

virtual

Close the file !!! File object no longer valid after this call !!!

Must call File::close() for each successful File::open() call.

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

Definition at line 187 of file File.cpp.

close() [2/2]

virtual void File::close ( void )

virtual

Close the file !!! File object no longer valid after this call !!!

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

convertToRAMFile()

virtual File * File::convertToRAMFile ( )

pure virtual

Implemented in LocalFile, RAMFile, and StreamingArchiveFile.

Create()

File::EFileError File::Create ( void )

virtual

Create a new file.

Definition at line 474 of file File.cpp.

Delete()

File::EFileError File::Delete ( void )

virtual

Delete an existing file.

Definition at line 508 of file File.cpp.

deleteOnClose() [1/2]

void File::deleteOnClose ( void )

inline

Causes the File object to delete itself when it closes.

Definition at line 188 of file file.h.

deleteOnClose() [2/2]

void File::deleteOnClose

(

void

)

Causes the File object to delete itself when it closes.

eof()

Bool File::eof

(

)

Definition at line 257 of file File.cpp.

Flush()

void File::Flush ( void )

virtual

Flush the stream.

Implements Stream.

Definition at line 1107 of file File.cpp.

getAccess() [1/2]

Int File::getAccess ( void )

inline

Returns file's access flags.

Definition at line 158 of file WSYS_file.h.

getAccess() [2/2]

Int File::getAccess ( void ) const

inline

Returns file's access flags.

Definition at line 187 of file file.h.

GetBytes()

UInt32 File::GetBytes ( void * ptr, UInt32 bytes )

virtual

Read bytes from the file.

Implements Stream.

Definition at line 946 of file File.cpp.

GetLength()

UInt32 File::GetLength ( void )

virtual

Get the length of the file.

Implements Stream.

Definition at line 768 of file File.cpp.

GetMarker()

UInt32 File::GetMarker ( void )

virtual

Get file position marker.

Implements Stream.

Definition at line 847 of file File.cpp.

GetName()

const UString & File::GetName

(

void

)

const

Retrieve name of file.

Definition at line 156 of file File.cpp.

getName() [1/3]

Bool File::getName	(	Char *	buffer,
		Int	max )

Copies the name of the file to the buffer.

Definition at line 229 of file WSYS_File.cpp.

getName() [2/3]

Char * File::getName ( void )

inline

Returns a pointer to the name of the file.

Definition at line 157 of file WSYS_file.h.

getName() [3/3]

const char * File::getName ( void ) const

inline

Returns a pointer to the name of the file.

Definition at line 185 of file file.h.

GetRights()

ERights File::GetRights ( void ) const

virtual

Retrieve file access rights.

Definition at line 201 of file File.cpp.

IsAvailable()

bool File::IsAvailable ( bool force = false )

virtual

Check if the file is available.

Definition at line 247 of file File.cpp.

IsOpen()

bool File::IsOpen ( void ) const

virtual

Check if te file is open.

Definition at line 307 of file File.cpp.

Load()

File::EFileError File::Load ( void *& outBuffer, UInt32 & outSize )

virtual

Load the file into memory.

Definition at line 550 of file File.cpp.

nextLine()

virtual void File::nextLine ( Char * buf = NULL, Int bufSize = 0 )

pure virtual

reads until it reaches a new-line character

Implemented in LocalFile, RAMFile, and StreamingArchiveFile.

OnFileError()

bool File::OnFileError ( EFileError error, bool canRetry )

virtual

Error handling hook.

Definition at line 729 of file File.cpp.

Open() [1/2]

File::EFileError File::Open ( const UString & name, ERights rights )

virtual

Open the file with the associated name for access.

Definition at line 423 of file File.cpp.

Open() [2/2]

File::EFileError File::Open ( ERights rights )

virtual

Open the file for access.

Definition at line 329 of file File.cpp.

open() [1/2]

Bool File::open ( const Char * filename, Int access = 0 )

virtual

Open a file for access.

Any derived open() members must first call File::open. If File::open succeeds but the derived class's open failes then make sure to call File::close() before returning.

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

Definition at line 138 of file File.cpp.

open() [2/2]

virtual Bool File::open ( const Char * filename, Int access = 0 )

virtual

Open a file for access.

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

PeekBytes()

UInt32 File::PeekBytes ( void * ptr, UInt32 bytes )

virtual

Read bytes from the file without marker adjustment.

Implements Stream.

Definition at line 1077 of file File.cpp.

position() [1/2]

Int File::position ( void )

virtual

Returns the current read/write position.

Definition at line 223 of file File.cpp.

position() [2/2]

virtual Int File::position ( void )

virtual

Returns the current read/write position.

print()

Bool File::print ( const Char * format, ... )

virtual

Prints formated string to text file.

Definition at line 232 of file File.cpp.

printf()

Bool File::printf ( const Char * format, ... )

virtual

Prints formated string to text file.

Definition at line 244 of file WSYS_File.cpp.

PutBytes()

UInt32 File::PutBytes ( const void * ptr, UInt32 bytes )

virtual

Write bytes to the file.

Implements Stream.

Definition at line 1015 of file File.cpp.

read() [1/2]

virtual Int File::read ( void * buffer, Int bytes )

virtual

Read the specified number of bytes from the file in to the memory pointed at by buffer. Returns the number of bytes read. Returns -1 if an error occured.

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

read() [2/2]

virtual Int File::read ( void * buffer, Int bytes )

virtual

Read the specified number of bytes from the file in to the memory pointed at by buffer. Returns the number of bytes read. Returns -1 if an error occured.

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

readEntireAndClose()

virtual char * File::readEntireAndClose ( )

pure virtual

Allocate a buffer large enough to hold entire file, read the entire file into the buffer, then close the file. the buffer is owned by the caller, who is responsible for freeing is (via delete[]). This is a Good Thing to use because it minimizes memory copies for BIG files.

Implemented in LocalFile, RAMFile, and StreamingArchiveFile.

Save()

File::EFileError File::Save ( const void * buffer, UInt32 size )

virtual

Write file data.

Definition at line 658 of file File.cpp.

scanInt()

virtual Bool File::scanInt ( Int & newInt )

pure virtual

read an integer from the current file position.

Implemented in LocalFile, RAMFile, and StreamingArchiveFile.

scanReal()

virtual Bool File::scanReal ( Real & newReal )

pure virtual

read a real number from the current file position.

Implemented in LocalFile, RAMFile, and StreamingArchiveFile.

scanString()

virtual Bool File::scanString ( AsciiString & newString )

pure virtual

read a string from the current file position.

Implemented in LocalFile, RAMFile, and StreamingArchiveFile.

seek() [1/2]

virtual Int File::seek ( Int bytes, seekMode mode = CURRENT )

virtual

Sets the file position of the next read/write operation. Returns the new file position as the number of bytes from the start of the file. Returns -1 if an error occured.

seekMode determines how the seek is done:

START : means seek to the specified number of bytes from the start of the file CURRENT: means seek the specified the number of bytes from the current file position END: means seek the specified number of bytes back from the end of the file

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

seek() [2/2]

virtual Int File::seek ( Int bytes, seekMode mode = CURRENT )

virtual

Sets the file position of the next read/write operation. Returns the new file position as the number of bytes from the start of the file. Returns -1 if an error occured.

seekMode determines how the seek is done:

START : means seek to the specified number of bytes from the start of the file CURRENT: means seek the specified the number of bytes from the current file position END: means seek the specified number of bytes back from the end of the file

Reimplemented in LocalFile, RAMFile, RAMFile, StdFile, and StreamingArchiveFile.

SetLength()

void File::SetLength ( UInt32 length )

virtual

Set the length of the file.

Implements Stream.

Definition at line 816 of file File.cpp.

SetMarker()

void File::SetMarker ( Int32 offset, EStreamFrom from )

virtual

Set file position marker.

Implements Stream.

Definition at line 870 of file File.cpp.

SetName()

void File::SetName ( const UString & name )

virtual

Associate a name to the file.

Definition at line 179 of file File.cpp.

setName() [1/2]

void File::setName

(

const Char *

name

)

Set the name of the file.

setName() [2/2]

void File::setName ( const char * name )

inline

Set the name of the file.

Definition at line 186 of file file.h.

SetRights()

void File::SetRights ( ERights rights )

virtual

Set file access rights.

Definition at line 223 of file File.cpp.

size() [1/2]

Int File::size ( void )

virtual

Returns the size of the file.

Default implementation of File::size. Derived classes can optimize this member function.

Definition at line 209 of file File.cpp.

size() [2/2]

virtual Int File::size ( void )

virtual

Returns the size of the file.

write() [1/2]

virtual Int File::write ( const void * buffer, Int bytes )

virtual

Write the specified number of bytes from the
memory pointed at by buffer to the file. Returns the number of bytes written. Returns -1 if an error occured.

Reimplemented in LocalFile, RAMFile, and StreamingArchiveFile.

write() [2/2]

virtual Int File::write ( void * buffer, Int bytes )

virtual

Write the specified number of bytes from the
memory pointed at by buffer to the file. Returns the number of bytes written. Returns -1 if an error occured.

Reimplemented in RAMFile, and StdFile.

Friends And Related Symbol Documentation

FileSystem

friend class FileSystem

friend

Definition at line 76 of file WSYS_file.h.

Member Data Documentation

m_access

Int File::m_access

protected

How the file was opened.

Definition at line 117 of file file.h.

m_deleteOnClose

Bool File::m_deleteOnClose

protected

delete File object on close()

Definition at line 119 of file file.h.

m_name

Char File::m_name[IO_MAX_PATH+1]

protected

Stores file name.

Definition at line 103 of file WSYS_file.h.

m_nameStr

AsciiString File::m_nameStr

protected

Stores file name.

Definition at line 116 of file file.h.

m_open

Bool File::m_open

protected

Has the file been opened.

Definition at line 118 of file file.h.

---

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

• Code/GameEngine/Include/Common/file.h
• Code/Tools/Autorun/WSYS_file.h
• Code/Tools/Launcher/Toolkit/Storage/File.h
• Code/GameEngine/Source/Common/System/File.cpp
• Code/Tools/Autorun/WSYS_File.cpp
• Code/Tools/Launcher/Toolkit/Storage/File.cpp