Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages | Examples

PG_FileArchive Class Reference

Inheritance diagram for PG_FileArchive:

Inheritance graph
[legend]
List of all members.

Detailed Description

A C++ wrapper for the PhysicsFS.

Author:
Alexander Pipelka


Public Types

enum  Mode { READ, WRITE, APPEND }
 File open mode. More...


Public Member Functions

 PG_FileArchive ()
 ~PG_FileArchive ()

Static Public Member Functions

void Deinit ()
bool AddArchive (const char *arch, bool append=true)
 Add a directory or archive file to the pool.

bool RemoveArchive (const char *arch)
 Remove a directory or archive file from the pool.

bool RemoveAllArchives ()
 Remove all currently registered directories or archive files from the pool.

char ** GetSearchPath ()
 Get a list of registered archives.

void FreeList (void *list)
 Free a list of entries.

char ** EnumerateFiles (const char *dir)
 Get a list of files in a directory.

bool Exists (const char *filename)
 Check if a file exists in the archive.

bool IsDirectory (const char *filename)
 Check if the "filename" is a directory.

const char * GetDirSeparator ()
 Get the platform specifiy directory separator.

const char * GetRealDir (const char *filename)
const char * GetLastError ()
bool MakeDir (const char *dir)
 Create a new directory.

bool SetWriteDir (const char *dir)
 Set write directory.

string * PathToPlatform (const char *path)
 convert a path from UNIX to system dependent format

const char * GetBaseDir ()
 Get the application base directory.

const char * GetUserDir ()
 Get the users home directory.

const char * GetWriteDir ()
 Get the designated write directory.

bool SetSaneConfig (const char *organization, const char *appName, const char *archiveExt=0, bool includeCdRoms=false, bool archivesFirst=true)
 Setup a sane config for a typical application.

PG_FileOpenFile (const char *filename, Mode mode=READ)
 Open a file from the archive.

SDL_RWops * OpenFileRWops (const char *filename, Mode mode=READ)
 Open a file from the archive.

PG_DataContainerReadFile (const char *filename)
 Open and read a file from the archive.

SDL_Surface * LoadSurface (const char *filename, bool convert=false)
 Load a surface (image) from the archive all loaded surface will be cached.

SDL_Surface * LoadSurface (const char *filename, bool usekey, Uint32 colorkey, bool convert=false)
 Load a surface (image) from the archive and apply a colorkey all loaded surface will be cached.

bool UnloadSurface (SDL_Surface *surface, bool bDeleteIfNotExists=true)
 Removes the surface from the cache.

void EnableSymlinks (bool followSymlinks)
 Enable / disable the use of symlinks.

PG_FileListGetSearchPathList ()
 Get the names of all registered archives.

PG_FileListGetFileList (const char *dir, const char *wildcard="*")
 Get the names of all files in a directory.


Member Enumeration Documentation

enum PG_FileArchive::Mode
 

File open mode.

Enumeration values:
READ  Open file for reading.
WRITE  Open file for writing.
APPEND  Open file for writing, appending data to the end of the file.


Constructor & Destructor Documentation

PG_FileArchive::PG_FileArchive  ) 
 

PG_FileArchive::~PG_FileArchive  ) 
 


Member Function Documentation

bool PG_FileArchive::AddArchive const char *  arch,
bool  append = true
[static]
 

Add a directory or archive file to the pool.

Parameters:
arch directorypath or filename
append true - append / false - prepend
Returns:
true on success

void PG_FileArchive::Deinit  )  [static]
 

void PG_FileArchive::EnableSymlinks bool  followSymlinks  )  [static]
 

Enable / disable the use of symlinks.

By default, the file I/O routines will check if a file is really a symlink during open calls and fail if it is. Otherwise, the link could take you outside the write and search paths, and compromise security.

Symbolic link permission can be enabled or disabled at any time, and is disabled by default

char** PG_FileArchive::EnumerateFiles const char *  dir  )  [static]
 

Get a list of files in a directory.

This function returns a NULL terminated char ** with the files in the specified directory. If the directory doesn't exist, NULL is returned.

Note:
The caller is responsible for freeing the array and the directories within the array.
Parameters:
dir directory to list files in
Returns:
the file list

bool PG_FileArchive::Exists const char *  filename  )  [static]
 

Check if a file exists in the archive.

Parameters:
filename file to check
Returns:
true if the file exists

void PG_FileArchive::FreeList void *  list  )  [static]
 

Free a list of entries.

This function returns frees a previously retrieved list (GetSearchPath()).

Parameters:
list the list to free

const char* PG_FileArchive::GetBaseDir  )  [static]
 

Get the application base directory.

Returns:
the application base directory

const char* PG_FileArchive::GetDirSeparator  )  [static]
 

Get the platform specifiy directory separator.

Returns:
pointer to separator string

PG_FileList* PG_FileArchive::GetFileList const char *  dir,
const char *  wildcard = "*"
[static]
 

Get the names of all files in a directory.

This function returns a vector of strings containing the names of all files in the specified directory.

Note:
The caller owns the returned vector and is responsible for deleting the returned structure.
Parameters:
dir directory to list files in
wildcard wildcard for file pattern matching
Returns:
the file list

const char* PG_FileArchive::GetLastError  )  [static]
 

const char* PG_FileArchive::GetRealDir const char *  filename  )  [static]
 

char** PG_FileArchive::GetSearchPath  )  [static]
 

Get a list of registered archives.

This function returns a NULL terminated char ** with all currently registered archives (AddArchive).

Note:
The caller is responsible for freeing the array and the entries within the array. (FreeList)
Returns:
the file list

PG_FileList* PG_FileArchive::GetSearchPathList  )  [static]
 

Get the names of all registered archives.

This function returns a vector of strings containing the names of all currently registered archives (Added via AddArchive)

Note:
The caller owns the returned vector and is responsible for deleting the returned structure.
Returns:
the file list

const char* PG_FileArchive::GetUserDir  )  [static]
 

Get the users home directory.

This functions tries to find the users home directory. If it can't find it, it returns a directory relative to the application base directory.

Returns:
the path to the user home directory

const char* PG_FileArchive::GetWriteDir  )  [static]
 

Get the designated write directory.

This function returns the directory which is opened for writing, if any.

Returns:
the directory opened for writing

bool PG_FileArchive::IsDirectory const char *  filename  )  [static]
 

Check if the "filename" is a directory.

Parameters:
filename filename to check
Returns:
true if it's a directory

SDL_Surface* PG_FileArchive::LoadSurface const char *  filename,
bool  usekey,
Uint32  colorkey,
bool  convert = false
[static]
 

Load a surface (image) from the archive and apply a colorkey all loaded surface will be cached.

Parameters:
filename imagefile to load
usekey true - apply colorkey
colorkey colorkey
convert convert the loaded surface into screen format (default = false)
Returns:
pointer to loaded SDL_Surface or NULL

SDL_Surface* PG_FileArchive::LoadSurface const char *  filename,
bool  convert = false
[static]
 

Load a surface (image) from the archive all loaded surface will be cached.

Parameters:
filename imagefile to load
convert convert the loaded surface into screen format (default = false)
Returns:
pointer to loaded SDL_Surface or NULL
Examples:
dblbuffer.cpp.

bool PG_FileArchive::MakeDir const char *  dir  )  [static]
 

Create a new directory.

This function tries to create a directory in the application write directory, if any.

Parameters:
dir directory name

PG_File* PG_FileArchive::OpenFile const char *  filename,
Mode  mode = READ
[static]
 

Open a file from the archive.

Parameters:
filename name of the file to open
mode the open mode
Returns:
pointer to newly created PG_File object or NULL

SDL_RWops* PG_FileArchive::OpenFileRWops const char *  filename,
Mode  mode = READ
[static]
 

Open a file from the archive.

Parameters:
filename name of the file to open
mode the open mode
Returns:
pointer SDL_RWops structure

string* PG_FileArchive::PathToPlatform const char *  path  )  [static]
 

convert a path from UNIX to system dependent format

This function converts / in a path to the system dependent format, which for example is \ in Windows and : on MacOS.

Parameters:
path path to convert
Returns:
a string with the converted path

PG_DataContainer* PG_FileArchive::ReadFile const char *  filename  )  [static]
 

Open and read a file from the archive.

This is a utility function which opens and reads a file in one step. The returned string should be deleted when it's not needed anymore.

Parameters:
filename name of file to read
Returns:
pointer to a string with the data of the named file or 0 if the file doesn't exist or was empty

bool PG_FileArchive::RemoveAllArchives  )  [static]
 

Remove all currently registered directories or archive files from the pool.

bool PG_FileArchive::RemoveArchive const char *  arch  )  [static]
 

Remove a directory or archive file from the pool.

Parameters:
arch directorypath or filename
Returns:
true on success

bool PG_FileArchive::SetSaneConfig const char *  organization,
const char *  appName,
const char *  archiveExt = 0,
bool  includeCdRoms = false,
bool  archivesFirst = true
[static]
 

Setup a sane config for a typical application.

This function is a convenience function which tries to open / create a directory in USERHOME/.organization/appName/ and add it as the write directory, add the base directory to the load path, optionally adds mounted cdroms to the searchpath and finally optiopnally adds files with the extension archiveExt to the load path (if any).

Parameters:
organization name of entity owning the application
appName name of application
archiveExt archive file extension to look for (0)
includeCdRoms whether to add mounted CDROMS to the search path (false)
archivesFirst put archive files before the real directory (true)
Returns:
true for success, false for failure

bool PG_FileArchive::SetWriteDir const char *  dir  )  [static]
 

Set write directory.

This function sets the write directory to use.

Parameters:
dir directory name

bool PG_FileArchive::UnloadSurface SDL_Surface *  surface,
bool  bDeleteIfNotExists = true
[static]
 

Removes the surface from the cache.

Parameters:
surface pointer to the SDL_Surface to remove
bDeleteIfNotExists delete (free) the surface if it isn't in the cache
Returns:
pointer to the SDL_Surface to remove


The ParaGUI Project - Alexander Pipelka