PG_FileArchive Class Reference

A C++ wrapper for the PhysicsFS. More...

#include <pgfilearchive.h>

Inheritance diagram for PG_FileArchive:

[legend]List of all members.


Public Types
enum	Mode { READ, WRITE, APPEND }
	File open mode. More...
Public Member Functions
	PG_FileArchive ()
	PG_FileArchive (const char *argv0)
	~PG_FileArchive ()
Static Public Member Functions
static void	Deinit ()
static bool	AddArchive (const std::string &arch, bool append=true)
	Add a directory or archive file to the pool.
static bool	RemoveArchive (const std::string &arch)
	Remove a directory or archive file from the pool.
static bool	RemoveAllArchives ()
	Remove all currently registered directories or archive files from the pool.
static char **	GetSearchPath ()
	Get a list of registered archives.
static void	FreeList (void *list)
	Free a list of entries.
static char **	EnumerateFiles (const std::string &dir)
	Get a list of files in a directory.
static bool	Exists (const std::string &filename)
	Check if a file exists in the archive.
static bool	IsDirectory (const std::string &filename)
	Check if the "filename" is a directory.
static const char *	GetDirSeparator ()
	Get the platform specifiy directory separator.
static const char *	GetRealDir (const std::string &filename)
static const char *	GetLastError ()
static bool	MakeDir (const std::string &dir)
	Create a new directory.
static bool	SetWriteDir (const std::string &dir)
	Set write directory.
static std::string *	PathToPlatform (const std::string &path)
	convert a path from UNIX to system dependent format
static const char *	GetBaseDir ()
	Get the application base directory.
static const char *	GetUserDir ()
	Get the users home directory.
static const char *	GetWriteDir ()
	Get the designated write directory.
static bool	SetSaneConfig (const std::string &organization, const std::string &appName, const std::string &archiveExt=PG_NULLSTR, bool includeCdRoms=false, bool archivesFirst=true)
	Setup a sane config for a typical application.
static PG_File *	OpenFile (const std::string &filename, Mode mode=READ)
	Open a file from the archive.
static SDL_RWops *	OpenFileRWops (const std::string &filename, Mode mode=READ)
	Open a file from the archive.
static PG_DataContainer *	ReadFile (const std::string &filename)
	Open and read a file from the archive.
static SDL_Surface *	LoadSurface (const std::string &filename, bool convert=false)
	Load a surface (image) from the archive all loaded surface will be cached.
static SDL_Surface *	LoadSurface (const std::string &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.
static bool	UnloadSurface (SDL_Surface *surface, bool bDeleteIfNotExists=true)
	Removes the surface from the cache.
static void	EnableSymlinks (bool followSymlinks)
	Enable / disable the use of symlinks.
static PG_FileList *	GetSearchPathList ()
	Get the names of all registered archives.
static PG_FileList *	GetFileList (const std::string &dir, const std::string &wildcard="*")
	Get the names of all files in a directory.

Detailed Description

A C++ wrapper for the PhysicsFS.

Author:: Alexander Pipelka

Definition at line 54 of file pgfilearchive.h.

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.

Definition at line 61 of file pgfilearchive.h.

Constructor & Destructor Documentation

PG_FileArchive::PG_FileArchive ( )

Definition at line 83 of file pgfilearchive.cpp.

PG_FileArchive::PG_FileArchive ( const char * argv0 )

Definition at line 90 of file pgfilearchive.cpp.

PG_FileArchive::~PG_FileArchive ( )

Definition at line 98 of file pgfilearchive.cpp.
References Deinit().

Member Function Documentation

bool PG_FileArchive::AddArchive ( const std::string & 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

Definition at line 144 of file pgfilearchive.cpp.
References PathToPlatform().
Referenced by ASC_PG_App::ASC_PG_App(), PG_Theme::Load(), PG_Application::LoadTheme(), and PG_Application::PG_Application().

void PG_FileArchive::Deinit ( ) [static]

Definition at line 118 of file pgfilearchive.cpp.
Referenced by ~PG_FileArchive().

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
Definition at line 419 of file pgfilearchive.cpp.
Referenced by ASC_PG_App::ASC_PG_App().

char ** PG_FileArchive::EnumerateFiles ( const std::string & 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

Definition at line 158 of file pgfilearchive.cpp.
Referenced by GetFileList().

bool PG_FileArchive::Exists ( const std::string & filename ) [static]

Check if a file exists in the archive.

Parameters:

filename file to check

Returns:
true if the file exists

Definition at line 183 of file pgfilearchive.cpp.
Referenced by PG_Application::GetRelativePath(), and PG_Theme::Load().

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

Definition at line 415 of file pgfilearchive.cpp.
Referenced by RemoveAllArchives().

const char * PG_FileArchive::GetBaseDir ( ) [static]

Get the application base directory.

Returns:
the application base directory

Definition at line 203 of file pgfilearchive.cpp.
Referenced by PG_Application::PG_Application().

const char * PG_FileArchive::GetDirSeparator ( ) [static]

Get the platform specifiy directory separator.

Returns:
pointer to separator string

Definition at line 191 of file pgfilearchive.cpp.
Referenced by PG_Theme::Load(), and PathToPlatform().

PG_FileList * PG_FileArchive::GetFileList ( const std::string & dir,

const std::string & 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

Definition at line 162 of file pgfilearchive.cpp.
References EnumerateFiles(), and fnmatch().

const char * PG_FileArchive::GetLastError ( ) [static]

Definition at line 199 of file pgfilearchive.cpp.
Referenced by PG_Theme::Load(), and LoadSurface().

const char * PG_FileArchive::GetRealDir ( const std::string & filename ) [static]

Definition at line 195 of file pgfilearchive.cpp.
Referenced by PG_Application::GetRelativePath(), and PG_Theme::Load().

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

Definition at line 385 of file pgfilearchive.cpp.
Referenced by RemoveAllArchives().

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

Definition at line 389 of file pgfilearchive.cpp.

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

Definition at line 207 of file pgfilearchive.cpp.

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

Definition at line 211 of file pgfilearchive.cpp.

bool PG_FileArchive::IsDirectory ( const std::string & filename ) [static]

Check if the "filename" is a directory.

Parameters:

filename filename to check

Returns:
true if it's a directory

Definition at line 187 of file pgfilearchive.cpp.

SDL_Surface * PG_FileArchive::LoadSurface ( const std::string & 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

Definition at line 304 of file pgfilearchive.cpp.
References PG_SurfaceCache::AddSurface(), PG_SurfaceCache::FindSurface(), GetLastError(), IMG_Load_RW_FUNC, PG_SurfaceCache::IncRef(), OpenFileRWops(), PG_LogERR(), and PG_LogWRN().

SDL_Surface * PG_FileArchive::LoadSurface ( const std::string & 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

Definition at line 300 of file pgfilearchive.cpp.
Referenced by PG_ThemeWidget::LoadImage(), parseObjectProps(), PG_ThemeWidget::SetBackground(), PG_Application::SetBackground(), PG_Label::SetIcon(), PG_Button::SetIcon(), and PG_Application::SetIcon().

bool PG_FileArchive::MakeDir ( const std::string & dir ) [static]

Create a new directory.
This function tries to create a directory in the application write directory, if any.
Parameters:

dir directory name

Definition at line 252 of file pgfilearchive.cpp.

PG_File * PG_FileArchive::OpenFile ( const std::string & 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

Definition at line 215 of file pgfilearchive.cpp.
References APPEND, READ, and WRITE.
Referenced by PG_Theme::Load(), PG_Layout::Load(), and ReadFile().

SDL_RWops * PG_FileArchive::OpenFileRWops ( const std::string & 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

Definition at line 235 of file pgfilearchive.cpp.
References APPEND, PHYSFSRWOPS_openAppend(), PHYSFSRWOPS_openRead(), PHYSFSRWOPS_openWrite(), READ, and WRITE.
Referenced by LoadSurface().

std::string * PG_FileArchive::PathToPlatform ( const std::string & 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

Definition at line 122 of file pgfilearchive.cpp.
References GetDirSeparator().
Referenced by AddArchive(), and RemoveArchive().

PG_DataContainer * PG_FileArchive::ReadFile ( const std::string & 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

Definition at line 273 of file pgfilearchive.cpp.
References PG_DataContainer::data(), PG_File::fileLength(), OpenFile(), and PG_File::read().
Referenced by PG_RichEdit::LoadText().

bool PG_FileArchive::RemoveAllArchives ( ) [static]

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

Definition at line 369 of file pgfilearchive.cpp.
References FreeList(), GetSearchPath(), PG_LogWRN(), and RemoveArchive().
Referenced by PG_Application::~PG_Application().

bool PG_FileArchive::RemoveArchive ( const std::string & arch ) [static]

Remove a directory or archive file from the pool.

Parameters:

arch directorypath or filename

Returns:
true on success

Definition at line 151 of file pgfilearchive.cpp.
References PathToPlatform().
Referenced by RemoveAllArchives().

bool PG_FileArchive::SetSaneConfig ( const std::string & organization,

const std::string & appName,

const std::string & archiveExt = PG_NULLSTR,

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

Definition at line 263 of file pgfilearchive.cpp.

bool PG_FileArchive::SetWriteDir ( const std::string & dir ) [static]

Set write directory.
This function sets the write directory to use.
Parameters:

dir directory name

Definition at line 255 of file pgfilearchive.cpp.

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

Definition at line 364 of file pgfilearchive.cpp.
References PG_SurfaceCache::DeleteSurface().
Referenced by PG_Application::DeleteBackground(), PG_WidgetDnD::eventMouseButtonUp(), PG_Application::eventQuit(), PG_Widget::FadeIn(), PG_Widget::FadeOut(), PG_Application::RedrawBackground(), PG_Application::SetBackground(), PG_Application::SetCursor(), PG_Label::SetIcon(), PG_Application::SetIcon(), PG_Application::Shutdown(), PG_Widget::SizeWidget(), PG_Label::~PG_Label(), PG_PopupMenu::~PG_PopupMenu(), PG_Widget::~PG_Widget(), and THEME_FILENAME::~THEME_FILENAME().

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

Generated on Tue Jun 24 02:18:53 2008 for Advanced Strategic Command by

1.4.2

PG_FileArchive Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation