CzFile respresents a file. More...

#include <CzFile.h>

Public Member Functions
CzFileHandle	getFileHandle ()
void	setFilename (const char *filename)
CzString &	getFilename ()
void	setFileAvailable (bool available)
bool	isFileAvailable ()
void	setFileAvailableCallback (CzCallback callback, void *data)
int	getFileSize ()
	Returns the size of the file in bytes.
eCzFileError	getError () const
void *	getContent ()
	Returns data that was downloaded.
int	getContentLength () const
	Gets downloaded contents length.
	CzFile ()
	CzFile (const char *filename)
virtual	~CzFile ()
bool	Open (const char filename=NULL, const char mode=NULL, bool blocking=false)
	Opens the file specified by path.
bool	Open (void *memory_buffer, int memory_buffer_len)
	Opens a memory buffer and provides file style access to it.
bool	Invalid ()
bool	Download ()
	Initiates down of the file.
bool	Read (void *buffer, int len)
	Reads len bytes from the file into buffer.
bool	Write (void *buffer, int len)
	Writes len bytes from buffer to the file.
bool	Seek (int offset, eCzFileSeekOrigin origin)
	Seeks the file positin pointer back and forth.
void	Close ()
	Closes the file.
void	FileReceived (CzHttpRequest *request, int error)
	Called when a flle download has finished.
Static Public Member Functions
static void	GetComponents (const char *file_path, CzFilePathComponents &components)
	Extracts the components of a file path.
static bool	GetFileType (const char *file_path, CzString &type)
	Gets file type (its extension).
static bool	isHttp (const char *file_path, int path_len)
	Query if 'file_path' is a web based file.
static bool	isFile (const char *file_path, int path_len)
	Query if 'file_path' is a file.
static bool	FileExists (const char *file_path)
	Queries if a given file exists.
static bool	DeleteFile (const char *file_path)
	Deletes the file described by file_path.
Protected Member Functions
void	NotifyAvailable ()
	Notifies the system that the file is available.
Protected Attributes
CzFileHandle	File
	File handle.
CzString	Filename
	Name of file.
bool	FileAvailable
	True when file is available.
CzCallback	FileAvailableCallback
	Callback to be called when file is available.
void *	FileAvailableCallbackData
	Callback data to be passed back with callback.
eCzFileError	Error
	Contains error code if any if file not received.
bool	InMemory
CzHttpRequest *	Request

Detailed Description

CzFile respresents a file.

Introduction

AppEasy encapsulates the file system neatly into a single class called CzFile. This class enables the following features:

Auto file close / cleanup when the file object goes out of scope
Reading and writing of local files
Reading and writing of memory based files
Blocking and none blocking reading of files from an external source such as a web site / server
File name splitting
File type retrieval

Loading a Local File

Loading a local file is very simple, as is shown in the following example:

// Here we declare a string, open a file then read some data into it
CzString data;
CzFile file;
if (file.Open("\\my_data.txt", "rb"))
{
    int len = file.getFileSize();
    data.allocString(len);
    data.setLength(len);
    file.Read((void*)data.c_str(), len);
}

Saving a Local File

Saving a local file is also a very simple, as is shown in the following example:

// Here we declare a string, open a file then write the string to it
CzString data("Hello storage, how you doing?");
CzFile file;
if (file.Open("\\my_data.txt", "wb"))
{
    file.Write((void*)data.c_str(), data.GetLength());
}

Loading a Memory Based File

Loading a memory file is just as easy as opening a local file, as is shown in the following example:

// Here we declare a string, open a file then read some data into it from memory
CzString data;
CzFile file;
if (file.Open(my_data_in_memory, my_data_length))
{
    int len = file.getFileSize();
    data.allocString(len);
    data.setLength(len);
    file.Read((void*)data.c_str(), len);
}

Loading a Remote File

The format of loading a file for remote is the same as local file loading

// Here we declare a string, open a remote file then read some data into it
CzString data;
CzFile file;
if (file.Open("http://www.myserver.com/my_data.txt", NULL, true))
{
    int len = file.getFileSize();
    data.allocString(len);
    data.setLength(len);
    file.Read((void*)data.c_str(), len);
}

With a few differences. The first differenece is the very noticable filename change to that of a web address. The second more subtle difference is the inlusion of a 3rd parameter to Open() which tells the method to block until the complete file has been downoaded or an error occurs.

With modern games / apps the user expects action on the screen most of the time, so sitting loading your assets from a server with no viusal update would not be a great idea, ruling blocking remote file loading out for anything more than a few files. A better alternative is to use asynchonrous file downloading that is none blocking, allowing the game loop to proceed whilst your assets load.

Loading a remote file using a none blocking method can be achieved as shown below:

int32 WebFileRetrievedCallback(void* caller, void* data)
{
    CzFile* file = (CzFile*)caller;

    // file->getContent() and file->getContentLength() contain the data and data size

    delete file;

    return 0;
}
    // Initiate a none blocking file  download
    CzFile* image_file = new CzFile();
    image_file->setFileAvailableCallback(WebFileRetrievedCallback, NULL);
    image_file->Open("http://www.battleballz.com/bb_icon.gif", NULL, false);

Examining the above code we can see that we set up a callback so that we get notified when our file has been downloaded. Next we initiate the file download but this time passing "false" as our blocking parameter to ensure that the download does not block the main thread.

If you don't fancy setting up a callback, you can poll the CzFile instead to see if the file has been retrieved using:

bool        CzFile::isFileAvailable()

Other Useful File Tools

CzFile also contains a few additional useful tool type methods:

static void GetComponents(const char* file_path, CzFilePathComponents& components); // Splits a path into its separate drive, path, name and extension components
static bool GetFileType(const char* file_path, CzString& type); // Returns the file type of the supplied file name
static bool isHttp(const char* file_path, int path_len); // Checks a file name to see if it uses the http protocol
static bool isFile(const char* file_path, int path_len); // Returns true if the path is a file (simple check for for an extension, will not work with url's)
static bool FileExists(const char* file_path);  // Returns true if the file exists
static bool DeleteFile(const char* file_path);  // Deletes a file

Todo:

Add none blocking file I/O
Add timeout check to blocking http download
Add methods for reading and writing common types
Add support for directory creation / removal
Add support directory / file discovery

Constructor & Destructor Documentation

CzFile::CzFile ( ) [inline]

CzFile::CzFile ( const char * filename ) [inline]

virtual CzFile::~CzFile ( ) [inline, virtual]

Member Function Documentation

void CzFile::Close ( )

Closes the file.

bool CzFile::DeleteFile ( const char * file_path ) [static]

Deletes the file described by file_path.

Parameters:

file_path Full pathname of the file.

Returns:: true if it succeeds, false if it fails.

bool CzFile::Download ( )

Initiates down of the file.

Returns:: true if it succeeds, false if it fails.

bool CzFile::FileExists ( const char * file_path ) [static]

Queries if a given file exists.

Parameters:

file_path Full pathname of the file.

Returns:: true if it exists, false if it does not.

void CzFile::FileReceived	(	CzHttpRequest *	request,
		int	error
	)

Called when a flle download has finished.

Parameters:

[in]	request	If non-null, the http request.
	error	The error if any.

void CzFile::GetComponents	(	const char *	file_path,
		CzFilePathComponents &	components
	)		`[static]`

Extracts the components of a file path.

Splits the supplied file path into path, filename and extension components.

Parameters:

	file_path	Full pathname of the file.
[out]	components	The components.

void * CzFile::getContent ( )

Returns data that was downloaded.

If a file is opened as a URL and the file has been downloaed then callnig getContent() will return the data that was downloaded.

Returns:: null if it fails, else the content.

int CzFile::getContentLength ( ) const

Gets downloaded contents length.

If a file is opened as a URL and the file has been downloaed then calling getContentLength() will return the size of the downloaded data.

Returns:: The content length.

eCzFileError CzFile::getError ( ) const [inline]

CzFileHandle CzFile::getFileHandle ( ) [inline]

CzString& CzFile::getFilename ( ) [inline]

int CzFile::getFileSize ( )

Returns the size of the file in bytes.

Returns:: The file size.

bool CzFile::GetFileType	(	const char *	file_path,
		CzString &	type
	)		`[static]`

Gets file type (its extension).

Parameters:

	file_path	Full pathname of the file.
[out]	type	The type.

Returns:: true if it succeeds, false if it fails.

bool CzFile::Invalid ( )

bool CzFile::isFile	(	const char *	file_path,
		int	path_len
	)		`[static]`

Query if 'file_path' is a file.

Note that this method does a simple check for the presence of a file extension. It will not work for http based files.

Parameters:

file_path	Full pathname of the file.
path_len	Length of the path.

Returns:: true if file, false if not.

bool CzFile::isFileAvailable ( ) [inline]

bool CzFile::isHttp	(	const char *	file_path,
		int	path_len
	)		`[static]`

Query if 'file_path' is a web based file.

Parameters:

file_path	Full pathname of the file.
path_len	Length of the path.

Returns:: true if http, false if not.

void CzFile::NotifyAvailable ( ) [protected]

Notifies the system that the file is available.

Calls the user supplied callback to notify the user that the file is loaded / downloaded and is available to use.

bool CzFile::Open	(	const char *	path = `NULL`,
		const char *	mode = `NULL`,
		bool	blocking = `false`
	)

Opens the file specified by path.

mode values are:

"r" Opens file for reading only
"w" Creates an empty file for writing. If file already exists then it is written over
"a" Opens file for appending. If file does not exist then it is created
"r+" Opens file for reading and writing. File must already exist
"w+" Creates an empty file for reading and writing. If file already exists then it is written over
"a+" Opens file for reading and appending. If file does not exist then it is created
"b" Opens the file in binary mode

If an error occurs then you can get more information about the error by calling getError()

Parameters:

path	Path of the file.
mode	The mode.
blocking	true to block whilst loading.

Returns:: true if it succeeds, false if it fails.

bool CzFile::Open	(	void *	memory_buffer,
		int	memory_buffer_len
	)

Opens a memory buffer and provides file style access to it.

Parameters:

[in,out]	memory_buffer	If non-null, buffer for memory data.
	memory_buffer_len	Length of the memory buffer.

Returns:: true if it succeeds, false if it fails.

bool CzFile::Read	(	void *	buffer,
		int	len
	)

Reads len bytes from the file into buffer.

Parameters:

[out]	buffer	If non-null, the buffer.
	len	Number of bytes to read.

Returns:: true if it succeeds, false if it fails.

bool CzFile::Seek	(	int	offset,
		eCzFileSeekOrigin	origin
	)

Seeks the file positin pointer back and forth.

Parameters:

offset	The offset.
origin	The origin.

Returns:: true if it succeeds, false if it fails.

void CzFile::setFileAvailable ( bool available ) [inline]

void CzFile::setFileAvailableCallback	(	CzCallback	callback,
		void *	data
	)		`[inline]`

void CzFile::setFilename ( const char * filename ) [inline]

bool CzFile::Write	(	void *	buffer,
		int	len
	)

Writes len bytes from buffer to the file.

Parameters:

[in]	buffer	If non-null, the buffer.
	len	Number of bytes to write.

Returns:: true if it succeeds, false if it fails.

Member Data Documentation

eCzFileError CzFile::Error [protected]

Contains error code if any if file not received.

CzFileHandle CzFile::File [protected]

File handle.

bool CzFile::FileAvailable [protected]

True when file is available.

CzCallback CzFile::FileAvailableCallback [protected]

Callback to be called when file is available.

void* CzFile::FileAvailableCallbackData [protected]

Callback data to be passed back with callback.

CzString CzFile::Filename [protected]

Name of file.

bool CzFile::InMemory [protected]

CzHttpRequest* CzFile::Request [protected]

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Introduction

Loading a Local File

Saving a Local File

Loading a Memory Based File

Loading a Remote File

Other Useful File Tools

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation