OSDL::EmbeddedFileSystemManager Class Reference

Allows to interact with embedded filesystem services, i.e. More...

#include <OSDLEmbeddedFileSystemManager.h>

Collaboration diagram for OSDL::EmbeddedFileSystemManager:

List of all members.

Public Member Functions

virtual void chooseBasicSettings (const std::string &organizationName, const std::string &applicationName, const std::string &archiveExtension="oar", bool archiveFirst=true, bool includeInsertedMedia=false)

Applies specified basic settings to the embedded filesystem: sets up sane, default paths, including a write directory chosen to be "user-directory"/.

virtual bool hasWriteDirectory () const

Tells whether the directory where the embedded filesystem will allow file writing is defined.

virtual std::string getWriteDirectory () const

Returns the directory where the embedded filesystem will allow file writing.

virtual void setWriteDirectory (const std::string &newWriteDirectory)

Sets a new write path, i.e.

virtual void mount (const std::string &newActualFilesystemElement, const std::string &mountPointInVirtualTree="", bool append=true)

Mounts specified element (directory or archive) from actual filesystem on specified mount point in virtual tree: add this element to the search path.

virtual void umount (const std::string &actualFilesystemElement)

Umounts specified element (directory or archive) of actual filesystem from virtual tree: removes this element from the search path.

virtual std::string getMountPointFor (const std::string &actualFilesystemElement) const

Returns the location in virtual tree (i.e.

virtual std::list< std::string > getSearchPath () const

Returns the current search path, i.e.

virtual bool existsAsEntry (const std::string &entryPath) const

Tells whether the filesystem entry entryPath exists, be it a file, a symbolic link, a directory, a character or block device, a FIFO, a socket, etc.

virtual void createSymbolicLink (const std::string &linkTarget, const std::string &linkName)

Not supported on embedded filesystems.

virtual time_t getEntryChangeTime (const std::string &entryPath)

Returns the change time time of the entry entryPath, be it a file, a directory, etc.

virtual const std::string & getRootDirectoryPrefix () const

virtual Ceylan::Latin1Char getSeparator () const

virtual Ceylan::System::File & createFile (const std::string &filename, Ceylan::System::OpeningFlag createFlag=Ceylan::System::File::CreateToWriteBinary, Ceylan::System::PermissionFlag permissionFlag=Ceylan::System::File::OwnerReadWrite)

Returns an EmbeddedFile reference on a newly created file.

virtual Ceylan::System::File & openFile (const std::string &filename, Ceylan::System::OpeningFlag openFlag=Ceylan::System::File::OpenToReadBinary)

Returns a File reference on specified already-existing file, which will be opened with specified settings.

virtual std::string getActualLocationFor (const std::string &filename) const

Returns the location in the search path where the specified filename can be found.

virtual bool existsAsFileOrSymbolicLink (const std::string &filename) const

Determines if the first occurence of filename in the search path is a symbolic link ( directory entry.

virtual bool existsAsSymbolicLink (const std::string &linkName) const

Tells whether the symbolic link filename exists.

virtual void removeFile (const std::string &filename)

Removes the file or symbolic link from the filesystem.

virtual void moveFile (const std::string &sourceFilename, const std::string &targetFilename)

Moves the file on filesystem.

virtual void copyFile (const std::string &sourceFilename, const std::string &targetFilename)

Copies the file on filesystem.

virtual Ceylan::System::Size getSize (const std::string &filename)

Returns the size, in bytes, of the specified file.

virtual time_t getLastChangeTimeFile (const std::string &filename)

Returns the last change time of the specified file.

virtual void touch (const std::string &filename)

Updates the last access and modification times of specified file.

virtual void allowSymbolicFiles (bool newStatus)

Enables or disables following of symbolic links.

virtual Ceylan::System::Directory & createDirectory (const std::string &newDirectoryName)

Returns a Directory reference on a directory newly created on filesystem.

virtual Ceylan::System::Directory & openDirectory (const std::string &directoryName="")

Returns a Directory reference on specified already-existing directory, which will be "opened" (i.e.

virtual bool existsAsDirectory (const std::string &directoryPath) const

Determines if the first occurence of directoryPath in the search path is really a directory entry.

virtual void removeDirectory (const std::string &directoryPath, bool recursive=false)

Removes the directory from filesystem.

virtual void moveDirectory (const std::string &sourceDirectoryPath, const std::string &targetDirectoryPath)

Moves the directory on filesystem.

virtual void copyDirectory (const std::string &sourceDirectoryPath, const std::string &targetDirectoryPath)

Copies the file on filesystem.

virtual time_t getLastChangeTimeDirectory (const std::string &directoryPath)

Returns the last change time of the specified directory.

virtual bool isAValidDirectoryPath (const std::string &directoryString)

Returns whether specified string is a valid directory path.

virtual bool isAbsolutePath (const std::string &path)

Tells whether specified path is an absolute path.

virtual std::string getCurrentWorkingDirectoryPath ()

Returns the current working directory path.

virtual void changeWorkingDirectory (const std::string &newWorkingDirectory)

Changes current working directory to newWorkingDirectory.

virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const

Returns a user-friendly description of the state of this object.

EmbeddedFileSystemManager (bool cypher=true)

Constructs a reference to an Embedded filesystem, initializes accordingly any needed subsystem.

virtual ~EmbeddedFileSystemManager () throw ()

Destroys the Ceylan embedded filesystem reference, not the filesystem itself.

Static Public Member Functions

static std::string GetBackendLastError ()

Returns the textual description of the latest error that occurred.

static Ceylan::Byte GetXORByte ()

Returns the XOR byte that should be used for XOR'd reads and writes, should cyphering be enabled.

static EmbeddedFileSystemManager & GetEmbeddedFileSystemManager (bool cypher=true)

Returns a reference to the unique embedded filesystem manager.

static bool SecureEmbeddedFileSystemManager ()

Ensures that the embedded filesystem manager is actually available, by instanciating it if necessary, and tells whether cyphering is enabled.

static void RemoveEmbeddedFileSystemManager ()

Removes the current embedded filesystem manager, if any.

static std::string FindArchivePath (const std::string &archiveFilename)

Helper method to find an OSDL archive specified by its filename, using archive locators.

Static Public Attributes

static std::string ArchivePathEnvironmentVariable

The name of the environment variable that may contain directory names that should contain embedded archive files.

static Ceylan::System::FileLocator ArchiveFileLocator

Allows to keep track of embedded archive directories.

Private Member Functions

EmbeddedFileSystemManager (const EmbeddedFileSystemManager &source)

Copy constructor made private to ensure that it will be never called.

EmbeddedFileSystemManager & operator= (const EmbeddedFileSystemManager &source)

Assignment operator made private to ensure that it will be never called.

Private Attributes

bool _cypher

Tells whether writes should be cyphered, and reads decyphered.

Static Private Attributes

static const Ceylan::Byte XORByte = 0x55

The byte that would be used for one cypher-pass against read and written bytes.

static const std::string RootDirectoryPrefix = ""

static const Ceylan::Latin1Char Separator = '/'

static EmbeddedFileSystemManager * _EmbeddedFileSystemManager = 0

Pointer to the current embedded filesystem manager (if any).

Detailed Description

Allows to interact with embedded filesystem services, i.e.

opaque files storing a (most usually read-only) virtual filesystem.

From the end-user point of view, only a small set of files and archives will be seen.

From the application point of view, read/write operations will be seamlessly performed on an abstract filesystem, stored in the set of opaque files and archives.

Default extension for archives is "OAR" (ex: "myArchive.oar"), for 'OSDL Archive'.

Based on PhysicsFS (http://icculus.org/physfs/), with added features for weak cypher, for example to avoid users messing to easily mess with saved games.

Use GetEmbeddedFileSystemManager to retrieve that manager.

Definition at line 83 of file OSDLEmbeddedFileSystemManager.h.

Constructor & Destructor Documentation

EmbeddedFileSystemManager::EmbeddedFileSystemManager ( bool cypher = true ) [explicit]

Constructs a reference to an Embedded filesystem, initializes accordingly any needed subsystem.

Cannot be private, as has to be subclassed. Cannot be protected, as has to be instanciated by factories from the mother class.

Parameters:

cypher

if true, writes to files will be cyphered, and obviously reads will be decyphered, so that the content of written files will not be directly readable. If false, raw I/O will be performed, with no further transformation.

Note:: Not to be called by the user.

See also:: GetEmbeddedFileSystemManager instead.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed.

Definition at line 1272 of file OSDLEmbeddedFileSystemManager.cc.

References _cypher, and GetBackendLastError().

Referenced by GetEmbeddedFileSystemManager().

EmbeddedFileSystemManager::~EmbeddedFileSystemManager ( ) throw () [virtual]

Destroys the Ceylan embedded filesystem reference, not the filesystem itself.

Cannot be private as has to be subclassed.

Definition at line 1344 of file OSDLEmbeddedFileSystemManager.cc.

References _EmbeddedFileSystemManager, and GetBackendLastError().

OSDL::EmbeddedFileSystemManager::EmbeddedFileSystemManager ( const EmbeddedFileSystemManager & source ) [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

void EmbeddedFileSystemManager::allowSymbolicFiles ( bool newStatus ) [virtual]

Enables or disables following of symbolic links.

Some physical filesystems and archives contain files that are just pointers to other files. On the physical filesystem, opening such a link will (transparently) open the file that is pointed to. By default, a file will be checked to know whether it is really a symlink during open calls and, the operation will fail if it is. Otherwise, the link could take you outside the write and search paths, and compromise security.

If you want to take that risk, call this function with a parameter set to true.

Note:: Not following links is mainly in order to sandbox a program's scripting language, in case untrusted scripts try to compromise the system. Generally speaking, a user could very well have a legitimate reason to set up a symlink.

Symlinks are only explicitly checked when dealing with filenames in platform-independent notation. That is, when setting up your search and write paths, etc, symlinks are never checked for.

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

Parameters:

newStatus

if true permits symlinks, if false denies linking.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed.

Definition at line 845 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::changeWorkingDirectory ( const std::string & newWorkingDirectory ) [virtual]

Changes current working directory to newWorkingDirectory.

Parameters:

newWorkingDirectory

the target working directory.

Exceptions:

DirectoryChangeFailed

if the operation failed or is not supported on the target platform.

Definition at line 1148 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::chooseBasicSettings	(	const std::string &	organizationName,
		const std::string &	applicationName,
		const std::string &	archiveExtension = `"oar"`,
		bool	archiveFirst = `true`,
		bool	includeInsertedMedia = `false`
	)			`[virtual]`

Applies specified basic settings to the embedded filesystem: sets up sane, default paths, including a write directory chosen to be "user-directory"/.

"organization"/"application", like, on UNIX: "~/.OSDL/MyTestApplication"

Parameters:

	organizationName	name of the company/group/etc. to be used as a directory name. Keep it small, and no-frills.
	applicationName	program-specific name of your application, to separate it from your other programs using an embedded filesystem.
	archiveExtension	the file extension used by your program to specify an archive. For example, Quake 3 uses "pk3", even though they are just zipfiles. OSDL users are encouraged to use "oar", which stands for the "OSDL Archive" format.

Do not specify the '.' char: if you want to look for ZIP files, specify "ZIP" and not ".ZIP". The archive search is case-insensitive.

Parameters:

	archiveFirst	if true, archives will be prepended to the search path. False will append them. This parameter will be ignored if archiveExtension is empty.
	includeInsertedMedia	if true, will include in the search path inserted disc media (such as DVD-ROM, HD-DVD, CDRW, and Blu-Ray discs) which store a filesystem, and if archiveExtension is not empty, will search them for archives. This may cause a significant amount of blocking while discs are accessed, and if there are no discs in the drive (or even not mounted on Unix systems), then they may not be made available anyhow. You may want to set this parameter to false here and handle the disc setup yourself.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed.

Note:: If a non-empty string is specified for archiveExtension, then all archives with this extension found in default paths will be automatically mounted. Therefore an empty string should be specified to not dig out archives automatically.

Definition at line 121 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

void EmbeddedFileSystemManager::copyDirectory	(	const std::string &	sourceDirectoryPath,
		const std::string &	targetDirectoryPath
	)			`[virtual]`

Copies the file on filesystem.

Parameters:

	sourceDirectoryPath	the path of the directory to be copied.
	targetDirectoryPath	the path of the target directory.

Exceptions:

DirectoryCopyFailed

if the operation failed or is not supported on this platform.

Definition at line 976 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::copyFile	(	const std::string &	sourceFilename,
		const std::string &	targetFilename
	)			`[virtual]`

Copies the file on filesystem.

Parameters:

	sourceFilename	the filename of the file to be copied.
	targetFilename	the new filename of the copied file.

Exceptions:

FileCopyFailed

if the operation failed or is not supported on this platform.

Definition at line 670 of file OSDLEmbeddedFileSystemManager.cc.

References bufferSize, OSDL::EmbeddedFile::close(), OSDL::EmbeddedFile::Create(), getSize(), OSDL::EmbeddedFile::Open(), OSDL::EmbeddedFile::read(), and OSDL::EmbeddedFile::write().

Directory & EmbeddedFileSystemManager::createDirectory ( const std::string & newDirectoryName ) [virtual]

Returns a Directory reference on a directory newly created on filesystem.

Parameters:

newDirectoryName

the name of the directory to create.

Note:: embeddedDirectory helper factory, has to be public but the user should not use it: Directory::Create is expected to be used instead, as it is the cross-platform factory intended for use.

Exceptions:

DirectoryException,including

DirectoryCreationFailed if the directory creation failed.

Definition at line 879 of file OSDLEmbeddedFileSystemManager.cc.

References OSDL::EmbeddedDirectory::Create().

virtual Ceylan::System::File& OSDL::EmbeddedFileSystemManager::createFile	(	const std::string &	filename,
		Ceylan::System::OpeningFlag	createFlag = `Ceylan::System::File::CreateToWriteBinary`,
		Ceylan::System::PermissionFlag	permissionFlag = `Ceylan::System::File::OwnerReadWrite`
	)			`[virtual]`

Returns an EmbeddedFile reference on a newly created file.

By default, it creates a new file on disk. If the name corresponds to an already-existing file, it will be truncated and overwritten.

Parameters:

	filename	the name of the file.
	createFlag	the flag describing the creation mode.
	permissionFlag	the flag describing the requested permissions. On platforms that do not manage permissions, this parameter will be ignored.

See also:: OpeningFlag, PermissionFlag

Note:: embeddedFile helper factory, has to be public but the user should not use it: File::Create is expected to be used instead, as it is the cross-platform factory intended for use.

Exceptions:

FileException,including

FileCreationFailed if the operation failed or is not supported on this platform.

void EmbeddedFileSystemManager::createSymbolicLink	(	const std::string &	linkTarget,
		const std::string &	linkName
	)			`[virtual]`

Not supported on embedded filesystems.

Exceptions:

SymlinkFailed

in all cases.

Definition at line 445 of file OSDLEmbeddedFileSystemManager.cc.

bool EmbeddedFileSystemManager::existsAsDirectory ( const std::string & directoryPath ) const [virtual]

Determines if the first occurence of directoryPath in the search path is really a directory entry.

Parameters:

directoryPath

the directory path to look-up, in platform-independent notation.

Exceptions:

DirectoryLookupFailed

if the operation failed (existence test failed with no answer) or is not supported on this platform.

Definition at line 899 of file OSDLEmbeddedFileSystemManager.cc.

bool EmbeddedFileSystemManager::existsAsEntry ( const std::string & entryPath ) const [virtual]

Tells whether the filesystem entry entryPath exists, be it a file, a symbolic link, a directory, a character or block device, a FIFO, a socket, etc.

Note:: The specified entry will searched through the full search path. Entries that are symlinks are ignored, unless the symlink status has been set to true.

Parameters:

entryPath

the path of the entry to look-up, in platform-independent notation.

Returns:: true iff the entry exists.

Exceptions:

EntryLookupFailed

if the operation failed (existence test failed with no answer) or is not supported on this platform.

Definition at line 419 of file OSDLEmbeddedFileSystemManager.cc.

bool EmbeddedFileSystemManager::existsAsFileOrSymbolicLink ( const std::string & filename ) const [virtual]

Determines if the first occurence of filename in the search path is a symbolic link ( directory entry.

Parameters:

directoryPath

the directory path to look-up, in platform-independent notation.

Exceptions:

DirectoryLookupFailed

if the operation failed (existence test failed with no answer) or is not supported on this platform. Tells whether the regular file or symbolic link filename exists (and is not a directory).

Parameters:

filename

the filename to look-up.

This method will work as expected whether the symbolic link feature is enabled or not.

Exceptions:

FileException,including

FileLookupFailed if the operation failed (existence test failed with no answer) or is not supported on this platform, or FileDelegatingException if the relevant filesystem manager could not be retrieved.

Note:: With embedded filesystems, one may use instead either getActualLocationFor or existsAsSymbolicLink.

Exceptions:

FileLookupFailed

in all cases.

Definition at line 573 of file OSDLEmbeddedFileSystemManager.cc.

bool EmbeddedFileSystemManager::existsAsSymbolicLink ( const std::string & linkName ) const [virtual]

Tells whether the symbolic link filename exists.

Parameters:

linkName

the filename to look-up.

This method will work as expected whether the symbolic link feature is enabled or not.

Exceptions:

FileLookupFailed

if the operation failed (existence test failed with no answer) or is not supported on this platform.

Definition at line 605 of file OSDLEmbeddedFileSystemManager.cc.

string EmbeddedFileSystemManager::FindArchivePath ( const std::string & archiveFilename ) [static]

Helper method to find an OSDL archive specified by its filename, using archive locators.

Note:: Starts by searching the current directory, before using the locator paths.

Parameters:

archiveFilename

the filename of the archive file.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed, including if the archive could not be found despite archive path locator.

Definition at line 1362 of file OSDLEmbeddedFileSystemManager.cc.

References ArchiveFileLocator, and ArchivePathEnvironmentVariable.

string EmbeddedFileSystemManager::getActualLocationFor ( const std::string & filename ) const [virtual]

Returns the location in the search path where the specified filename can be found.

The file is specified in platform-independent notation. The returned filename will be the element of the search path where the file was found, which may be a directory, or an archive. Even if there are multiple matches in different parts of the search path, only the first one found is used, just like when opening a file.

So, if you look for "maps/level1.map", and C:\mygame is in your search path and C:\mygame\maps\level1.map exists, then "C:\mygame" is returned.

If any part of a match is a symbolic link, and symlinks have not been explicitly permitted , then it will be ignored, and the search for a match will continue.

If you specify a fake directory that only exists as a mount point, it will be associated with the first archive mounted there, even though that directory is not necessarily contained in a real archive.

Parameters:

filename

the filename to look-up.

This method will work as expected whether the symbolic link feature is enabled or not.

Returns:: the full actual location of the specified file.

Exceptions:

FileLookupFailed

if the operation failed (existence test failed with no answer) or is not supported on this platform, or EmbeddedFileSystemManagerException is the file was not found.

Definition at line 538 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

std::string EmbeddedFileSystemManager::GetBackendLastError ( ) [static]

Returns the textual description of the latest error that occurred.

Definition at line 1190 of file OSDLEmbeddedFileSystemManager.cc.

Referenced by chooseBasicSettings(), OSDL::EmbeddedFile::close(), OSDL::EmbeddedDirectory::EmbeddedDirectory(), EmbeddedFileSystemManager(), getActualLocationFor(), getEntryChangeTime(), getLastChangeTimeDirectory(), getLastChangeTimeFile(), getMountPointFor(), getSearchPath(), mount(), removeDirectory(), removeFile(), OSDL::EmbeddedFile::reopen(), setWriteDirectory(), OSDL::EmbeddedFile::size(), OSDL::EmbeddedFile::tell(), umount(), and ~EmbeddedFileSystemManager().

std::string EmbeddedFileSystemManager::getCurrentWorkingDirectoryPath ( ) [virtual]

Returns the current working directory path.

Returns:: the path associated to the process, knowing that for embedded filesystems read and write paths can be different.

Exceptions:

DirectoryGetCurrentFailed

if the operation failed or is not supported on the target platform.

Definition at line 1052 of file OSDLEmbeddedFileSystemManager.cc.

EmbeddedFileSystemManager & EmbeddedFileSystemManager::GetEmbeddedFileSystemManager ( bool cypher = true ) [static]

Returns a reference to the unique embedded filesystem manager.

Parameters:

cypher

file reads and writes will be cyphered iff true.

Does not set this filesystem manager as the default one.

Creates it if needed: this method ensures it remains a singleton.

Must be public, as ancestor has to be able to call it.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed.

Definition at line 1226 of file OSDLEmbeddedFileSystemManager.cc.

References _EmbeddedFileSystemManager, and EmbeddedFileSystemManager().

Referenced by OSDL::EmbeddedFile::getCorrespondingFileSystemManager(), OSDL::EmbeddedDirectory::getCorrespondingFileSystemManager(), and SecureEmbeddedFileSystemManager().

time_t EmbeddedFileSystemManager::getEntryChangeTime ( const std::string & entryPath ) [virtual]

Returns the change time time of the entry entryPath, be it a file, a directory, etc.

Parameters:

entryPath

the path of the entry.

Exceptions:

GetChangeTimeFailed

if the operation failed or is not supported.

Definition at line 456 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

time_t EmbeddedFileSystemManager::getLastChangeTimeDirectory ( const std::string & directoryPath ) [virtual]

Returns the last change time of the specified directory.

Parameters:

directoryPath

the path of the directory whose last change time is searched.

Exceptions:

DirectoryLastChangeTimeRequestFailed

if the operation failed or is not supported on this platform.

Definition at line 987 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

time_t EmbeddedFileSystemManager::getLastChangeTimeFile ( const std::string & filename ) [virtual]

Returns the last change time of the specified file.

Parameters:

filename

the filename whose last change time is searched, in platform-independent notation.

Returns:: The modification time is returned as a number of seconds since the epoch (Jan 1, 1970).

Note:: The exact derivation and accuracy of this time depends on the particular archiver.

Exceptions:

FileLastChangeTimeRequestFailed

if the operation failed, if there is no reasonable way to obtain this information for a particular archiver, or if it is not supported on this platform.

Definition at line 801 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

std::string EmbeddedFileSystemManager::getMountPointFor ( const std::string & actualFilesystemElement ) const [virtual]

Returns the location in virtual tree (i.e.

the mount point) of the specified already-mounted actual filesystem element.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed (bogus archive, directory missing, etc.).

Definition at line 334 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

const string & EmbeddedFileSystemManager::getRootDirectoryPrefix ( ) const [virtual]

Definition at line 494 of file OSDLEmbeddedFileSystemManager.cc.

References RootDirectoryPrefix.

std::list< std::string > EmbeddedFileSystemManager::getSearchPath ( ) const [virtual]

Returns the current search path, i.e.

the ordered list of elements (directories or archives) from the actual filesystem that are scanned in turn when searching for a file in virtual tree.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed (bogus archive, directory missing, etc.).

Definition at line 367 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

Ceylan::Latin1Char EmbeddedFileSystemManager::getSeparator ( ) const [virtual]

Definition at line 503 of file OSDLEmbeddedFileSystemManager.cc.

References Separator.

Size EmbeddedFileSystemManager::getSize ( const std::string & filename ) [virtual]

Returns the size, in bytes, of the specified file.

Parameters:

filename

the filename whose size is searched.

Note:: The file size may not be determined (ex: since the archive is "streamed"). Also note that if another process/thread is writing to this file at the same time, then the information this function supplies could be incorrect before you get it. Use with caution, or better yet, do not use at all.

Exceptions:

FileSizeRequestFailed

if the operation failed (ex: file not found, size could not be determined, etc.) or is not supported on this platform.

Definition at line 761 of file OSDLEmbeddedFileSystemManager.cc.

Referenced by copyFile().

std::string EmbeddedFileSystemManager::getWriteDirectory ( ) const [virtual]

Returns the directory where the embedded filesystem will allow file writing.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed, including if no write directory was set.

Definition at line 188 of file OSDLEmbeddedFileSystemManager.cc.

Ceylan::Byte EmbeddedFileSystemManager::GetXORByte ( ) [static]

Returns the XOR byte that should be used for XOR'd reads and writes, should cyphering be enabled.

Definition at line 1201 of file OSDLEmbeddedFileSystemManager.cc.

References XORByte.

Referenced by OSDL::EmbeddedFile::CypherBuffer().

bool EmbeddedFileSystemManager::hasWriteDirectory ( ) const [virtual]

Tells whether the directory where the embedded filesystem will allow file writing is defined.

Definition at line 161 of file OSDLEmbeddedFileSystemManager.cc.

bool EmbeddedFileSystemManager::isAbsolutePath ( const std::string & path ) [virtual]

Tells whether specified path is an absolute path.

Parameters:

path

the path that may be absolute.

Definition at line 1032 of file OSDLEmbeddedFileSystemManager.cc.

References Separator.

bool EmbeddedFileSystemManager::isAValidDirectoryPath ( const std::string & directoryString ) [virtual]

Returns whether specified string is a valid directory path.

(i.e. checks the name can be used, does not look-up any real filesystem entry).

Parameters:

directoryString

the directory string to examine.

Note:: If no regular expression support is available, then the path will be deemed always correct.

Definition at line 1021 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::mount	(	const std::string &	newActualFilesystemElement,
		const std::string &	mountPointInVirtualTree = `""`,
		bool	append = `true`
	)			`[virtual]`

Mounts specified element (directory or archive) from actual filesystem on specified mount point in virtual tree: add this element to the search path.

When you mount an archive, it is added to a virtual file system. All files in all of the archives are referenced into a single virtual hierarchical file tree. Two archives mounted at the same place (or an archive with files overlapping another mountpoint) may have overlapping files: in such a case, the file earliest in the search path is selected, and the other files are inaccessible to the application. This allows archives to be used to override previous revisions; you can use the mounting mechanism to place archives at a specific point in the file tree and prevent overlap; this is useful for downloadable mods that might trample over application data or each other, for example.

The mountpoint does not need to exist prior to mounting, which is different than those, familiar with the Unix concept of "mounting", may not expect. As well, more than one archive can be mounted to the same mountpoint, or mountpoints and archive contents can overlap. The mechanism still functions as usual.

Parameters:

	newActualFilesystemElement	the directory or archive to add to the search path, in platform-dependent notation.
	mountPointInVirtualTree	location in the virtual tree this element will be mounted on, in platform-independent notation. An empty string is equivalent to "/".
	append	if true append to search path, otherwise prepend.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed (bogus archive, directory missing, etc.).

Definition at line 249 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

void EmbeddedFileSystemManager::moveDirectory	(	const std::string &	sourceDirectoryPath,
		const std::string &	targetDirectoryPath
	)			`[virtual]`

Moves the directory on filesystem.

A special case of directory moving is directory renaming.

Parameters:

	sourceDirectoryPath	the path of the directory to be moved.
	targetDirectoryPath	the path of the target directory.

Exceptions:

DirectoryMoveFailed

if the operation failed or is not supported on this platform.

Definition at line 965 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::moveFile	(	const std::string &	sourceFilename,
		const std::string &	targetFilename
	)			`[virtual]`

Moves the file on filesystem.

A special case of file moving is file renaming.

Parameters:

	sourceFilename	the filename of the file to be moved.
	targetFilename	the target filename of the moved file.

Note:: Operation not supported on embedded files.

Exceptions:

FileMoveFailed

in all cases.

Definition at line 659 of file OSDLEmbeddedFileSystemManager.cc.

Directory & EmbeddedFileSystemManager::openDirectory ( const std::string & directoryName = "" ) [virtual]

Returns a Directory reference on specified already-existing directory, which will be "opened" (i.e.

referred to).

Parameters:

directoryName

the name of the directory. If not specified (the string is empty), returns a reference to the current working directory.

Note:: embeddedDirectory helper factory, has to be public but the user should not use it: Directory::Open is expected to be used instead, as it is the cross-platform factory intended for use.

Exceptions:

DirectoryException,including

DirectoryOpeningFailed if the directory opening failed.

Definition at line 889 of file OSDLEmbeddedFileSystemManager.cc.

References OSDL::EmbeddedDirectory::Open().

virtual Ceylan::System::File& OSDL::EmbeddedFileSystemManager::openFile	(	const std::string &	filename,
		Ceylan::System::OpeningFlag	openFlag = `Ceylan::System::File::OpenToReadBinary`
	)			`[virtual]`

Returns a File reference on specified already-existing file, which will be opened with specified settings.

Parameters:

	filename	the name of the file.
	openFlag	the flag describing the opening mode.

See also:: OpeningFlag

Note:: embeddedFile helper factory, has to be public but the user should not use it: File::Open is expected to be used instead, as it is the cross-platform factory intended for use.

Exceptions:

FileException,including

FileOpeningFailed if the operation failed or is not supported on this platform.

EmbeddedFileSystemManager& OSDL::EmbeddedFileSystemManager::operator= ( const EmbeddedFileSystemManager & source ) [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void EmbeddedFileSystemManager::removeDirectory	(	const std::string &	directoryPath,
		bool	recursive = `false`
	)			`[virtual]`

Removes the directory from filesystem.

Parameters:

	directoryPath	the path of the target directory, specified in platform-independent notation in relation to the write directory.
	recursive	must be false, and the specified directory is expected to be empty. It will be removed. No automatic file deletion is offered, since the files in that directory could be eclipsed by identically named files found sooner in the search path.

Exceptions:

DirectoryRemoveFailed

if the operation failed or is not supported.

Definition at line 926 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

void EmbeddedFileSystemManager::RemoveEmbeddedFileSystemManager ( ) [static]

Removes the current embedded filesystem manager, if any.

Must be public, as ancestor has to be able to call it.

Note:: Removing such manager, if it was set as the default one, will remove it as well.

Definition at line 1252 of file OSDLEmbeddedFileSystemManager.cc.

References _EmbeddedFileSystemManager.

void EmbeddedFileSystemManager::removeFile ( const std::string & filename ) [virtual]

Removes the file or symbolic link from the filesystem.

Parameters:

filename

the filename to remove, specified in platform-independent notation in relation to the write directory.

Exceptions:

FileRemoveFailed

if the operation failed or is not supported on this platform.

So if the write directory is set to "C:\mygame\writedir" and filename to remove is "downloads/maps/level1.map", then the file "C:\mygame\writedir\downloads\maps\level1.map" is removed from the physical filesystem, if it exists and the operating system permits the deletion.

Note:: On Unix systems, deleting a file may be successful, but the actual file will not be removed until all processes that have an open filehandle to it (including your program) close their handles.

Chances are, the bits that make up the file still exist, they are just made available to be written over at a later point. Do not consider this a security method.

Definition at line 632 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

bool EmbeddedFileSystemManager::SecureEmbeddedFileSystemManager ( ) [static]

Ensures that the embedded filesystem manager is actually available, by instanciating it if necessary, and tells whether cyphering is enabled.

Does not set this filesystem manager as the default one.

Creates it if needed: this method ensures it remains a singleton.

Useful to ensure a static operation can rely on a preexisting manager.

Returns:: true iff I/O file cyphering is enabled.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed.

Definition at line 1239 of file OSDLEmbeddedFileSystemManager.cc.

References GetEmbeddedFileSystemManager().

Referenced by OSDL::EmbeddedDirectory::EmbeddedDirectory(), OSDL::CDROMDrive::GetListOfInsertedMedia(), OSDL::Utils::getProgramPath(), and OSDL::Utils::getUserDirectory().

void EmbeddedFileSystemManager::setWriteDirectory ( const std::string & newWriteDirectory ) [virtual]

Sets a new write path, i.e.

the directory where the embedded filesystem may write its files.

Parameters:

newWriteDirectory

the new directory to be the root of the write directory, specified in platform-dependent notation. Specifying an empty string disables the write directory, so that no file can be opened for writing via this embedded file system.

Note:: This call will fail (and fail to change the write directory) if at least a file remains open in the current write directory.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed.

Definition at line 220 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

const string EmbeddedFileSystemManager::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns a user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: TextDisplayable

Definition at line 1210 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::touch ( const std::string & filename ) [virtual]

Updates the last access and modification times of specified file.

This is not expected to work for directories.

Parameters:

filename

the filename of the file whose times must be updated.

Note:: On contrary to the UNIX command touch, if the specified file does not exist, it will not be created. A FileTouchFailed exception would be raised instead.

See also:: File::Create to create empty files.

Note:: Not supported on embedded files.

Exceptions:

FileTouchFailed

in all cases.

Definition at line 835 of file OSDLEmbeddedFileSystemManager.cc.

void EmbeddedFileSystemManager::umount ( const std::string & actualFilesystemElement ) [virtual]

Umounts specified element (directory or archive) of actual filesystem from virtual tree: removes this element from the search path.

This must be a (case-sensitive) match to a directory or archive already in the search path, specified in platform-dependent notation.

Parameters:

actualFilesystemElement

the directory or archive to remove from search path.

Note:: This call will fail (and fail to remove the element) if at least a file remains open in it.

Exceptions:

EmbeddedFileSystemManagerException

if the operation failed (bogus archive, directory missing, etc.).

Definition at line 305 of file OSDLEmbeddedFileSystemManager.cc.

References GetBackendLastError().

Member Data Documentation

bool OSDL::EmbeddedFileSystemManager::_cypher [private]

Tells whether writes should be cyphered, and reads decyphered.

Definition at line 1157 of file OSDLEmbeddedFileSystemManager.h.

Referenced by EmbeddedFileSystemManager().

EmbeddedFileSystemManager * EmbeddedFileSystemManager::_EmbeddedFileSystemManager = 0 [static, private]

Pointer to the current embedded filesystem manager (if any).

Definition at line 1220 of file OSDLEmbeddedFileSystemManager.h.

Referenced by GetEmbeddedFileSystemManager(), RemoveEmbeddedFileSystemManager(), and ~EmbeddedFileSystemManager().

Ceylan::System::FileLocator EmbeddedFileSystemManager::ArchiveFileLocator [static]

Allows to keep track of embedded archive directories.

Automatically gathers the list of directories specified as the value of the environment variable named as specified in ArchivePathEnvironmentVariable (ARCHIVE_PATH).

Definition at line 1125 of file OSDLEmbeddedFileSystemManager.h.

Referenced by FindArchivePath().

string EmbeddedFileSystemManager::ArchivePathEnvironmentVariable [static]

Initial value:

 
    "ARCHIVE_PATH"

The name of the environment variable that may contain directory names that should contain embedded archive files.

Definition at line 1112 of file OSDLEmbeddedFileSystemManager.h.

Referenced by FindArchivePath().

const string EmbeddedFileSystemManager::RootDirectoryPrefix = "" [static, private]

Definition at line 1180 of file OSDLEmbeddedFileSystemManager.h.

Referenced by getRootDirectoryPrefix().

const Ceylan::Latin1Char EmbeddedFileSystemManager::Separator = '/' [static, private]

Definition at line 1189 of file OSDLEmbeddedFileSystemManager.h.

Referenced by getSeparator(), and isAbsolutePath().

const Ceylan::Byte EmbeddedFileSystemManager::XORByte = 0x55 [static, private]

The byte that would be used for one cypher-pass against read and written bytes.

Definition at line 1166 of file OSDLEmbeddedFileSystemManager.h.

Referenced by GetXORByte().

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


Public Member Functions
virtual void	chooseBasicSettings (const std::string &organizationName, const std::string &applicationName, const std::string &archiveExtension="oar", bool archiveFirst=true, bool includeInsertedMedia=false)
	Applies specified basic settings to the embedded filesystem: sets up sane, default paths, including a write directory chosen to be "user-directory"/.
virtual bool	hasWriteDirectory () const
	Tells whether the directory where the embedded filesystem will allow file writing is defined.
virtual std::string	getWriteDirectory () const
	Returns the directory where the embedded filesystem will allow file writing.
virtual void	setWriteDirectory (const std::string &newWriteDirectory)
	Sets a new write path, i.e.
virtual void	mount (const std::string &newActualFilesystemElement, const std::string &mountPointInVirtualTree="", bool append=true)
	Mounts specified element (directory or archive) from actual filesystem on specified mount point in virtual tree: add this element to the search path.
virtual void	umount (const std::string &actualFilesystemElement)
	Umounts specified element (directory or archive) of actual filesystem from virtual tree: removes this element from the search path.
virtual std::string	getMountPointFor (const std::string &actualFilesystemElement) const
	Returns the location in virtual tree (i.e.
virtual std::list< std::string >	getSearchPath () const
	Returns the current search path, i.e.
virtual bool	existsAsEntry (const std::string &entryPath) const
	Tells whether the filesystem entry entryPath exists, be it a file, a symbolic link, a directory, a character or block device, a FIFO, a socket, etc.
virtual void	createSymbolicLink (const std::string &linkTarget, const std::string &linkName)
	Not supported on embedded filesystems.
virtual time_t	getEntryChangeTime (const std::string &entryPath)
	Returns the change time time of the entry entryPath, be it a file, a directory, etc.
virtual const std::string &	getRootDirectoryPrefix () const
virtual Ceylan::Latin1Char	getSeparator () const
virtual Ceylan::System::File &	createFile (const std::string &filename, Ceylan::System::OpeningFlag createFlag=Ceylan::System::File::CreateToWriteBinary, Ceylan::System::PermissionFlag permissionFlag=Ceylan::System::File::OwnerReadWrite)
	Returns an EmbeddedFile reference on a newly created file.
virtual Ceylan::System::File &	openFile (const std::string &filename, Ceylan::System::OpeningFlag openFlag=Ceylan::System::File::OpenToReadBinary)
	Returns a File reference on specified already-existing file, which will be opened with specified settings.
virtual std::string	getActualLocationFor (const std::string &filename) const
	Returns the location in the search path where the specified filename can be found.
virtual bool	existsAsFileOrSymbolicLink (const std::string &filename) const
	Determines if the first occurence of filename in the search path is a symbolic link ( directory entry.
virtual bool	existsAsSymbolicLink (const std::string &linkName) const
	Tells whether the symbolic link filename exists.
virtual void	removeFile (const std::string &filename)
	Removes the file or symbolic link from the filesystem.
virtual void	moveFile (const std::string &sourceFilename, const std::string &targetFilename)
	Moves the file on filesystem.
virtual void	copyFile (const std::string &sourceFilename, const std::string &targetFilename)
	Copies the file on filesystem.
virtual Ceylan::System::Size	getSize (const std::string &filename)
	Returns the size, in bytes, of the specified file.
virtual time_t	getLastChangeTimeFile (const std::string &filename)
	Returns the last change time of the specified file.
virtual void	touch (const std::string &filename)
	Updates the last access and modification times of specified file.
virtual void	allowSymbolicFiles (bool newStatus)
	Enables or disables following of symbolic links.
virtual Ceylan::System::Directory &	createDirectory (const std::string &newDirectoryName)
	Returns a Directory reference on a directory newly created on filesystem.
virtual Ceylan::System::Directory &	openDirectory (const std::string &directoryName="")
	Returns a Directory reference on specified already-existing directory, which will be "opened" (i.e.
virtual bool	existsAsDirectory (const std::string &directoryPath) const
	Determines if the first occurence of directoryPath in the search path is really a directory entry.
virtual void	removeDirectory (const std::string &directoryPath, bool recursive=false)
	Removes the directory from filesystem.
virtual void	moveDirectory (const std::string &sourceDirectoryPath, const std::string &targetDirectoryPath)
	Moves the directory on filesystem.
virtual void	copyDirectory (const std::string &sourceDirectoryPath, const std::string &targetDirectoryPath)
	Copies the file on filesystem.
virtual time_t	getLastChangeTimeDirectory (const std::string &directoryPath)
	Returns the last change time of the specified directory.
virtual bool	isAValidDirectoryPath (const std::string &directoryString)
	Returns whether specified string is a valid directory path.
virtual bool	isAbsolutePath (const std::string &path)
	Tells whether specified path is an absolute path.
virtual std::string	getCurrentWorkingDirectoryPath ()
	Returns the current working directory path.
virtual void	changeWorkingDirectory (const std::string &newWorkingDirectory)
	Changes current working directory to newWorkingDirectory.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns a user-friendly description of the state of this object.
	EmbeddedFileSystemManager (bool cypher=true)
	Constructs a reference to an Embedded filesystem, initializes accordingly any needed subsystem.
virtual	~EmbeddedFileSystemManager () throw ()
	Destroys the Ceylan embedded filesystem reference, not the filesystem itself.
Static Public Member Functions
static std::string	GetBackendLastError ()
	Returns the textual description of the latest error that occurred.
static Ceylan::Byte	GetXORByte ()
	Returns the XOR byte that should be used for XOR'd reads and writes, should cyphering be enabled.
static EmbeddedFileSystemManager &	GetEmbeddedFileSystemManager (bool cypher=true)
	Returns a reference to the unique embedded filesystem manager.
static bool	SecureEmbeddedFileSystemManager ()
	Ensures that the embedded filesystem manager is actually available, by instanciating it if necessary, and tells whether cyphering is enabled.
static void	RemoveEmbeddedFileSystemManager ()
	Removes the current embedded filesystem manager, if any.
static std::string	FindArchivePath (const std::string &archiveFilename)
	Helper method to find an OSDL archive specified by its filename, using archive locators.
Static Public Attributes
static std::string	ArchivePathEnvironmentVariable
	The name of the environment variable that may contain directory names that should contain embedded archive files.
static Ceylan::System::FileLocator	ArchiveFileLocator
	Allows to keep track of embedded archive directories.
Private Member Functions
	EmbeddedFileSystemManager (const EmbeddedFileSystemManager &source)
	Copy constructor made private to ensure that it will be never called.
EmbeddedFileSystemManager &	operator= (const EmbeddedFileSystemManager &source)
	Assignment operator made private to ensure that it will be never called.
Private Attributes
bool	_cypher
	Tells whether writes should be cyphered, and reads decyphered.
Static Private Attributes
static const Ceylan::Byte	XORByte = 0x55
	The byte that would be used for one cypher-pass against read and written bytes.
static const std::string	RootDirectoryPrefix = ""
static const Ceylan::Latin1Char	Separator = '/'
static EmbeddedFileSystemManager *	_EmbeddedFileSystemManager = 0
	Pointer to the current embedded filesystem manager (if any).