OSDL::EmbeddedFile Class Reference

Encapsulates embedded files, i.e. More...

#include <OSDLEmbeddedFile.h>

Public Member Functions
virtual	~EmbeddedFile () throw ()
	Destroys the embedded file reference object, does not remove the file itself.
virtual bool	isOpen () const
	Returns true iff this file is open.
virtual bool	close ()
	Closes the file for read/write actions.
virtual void	saveAs (const std::string &newName)
	Saves the file under a new name.
virtual void	lockForReading () const
	Locks the file for reading.
virtual void	unlockForReading () const
	Unlocks the file for reading.
virtual void	lockForWriting () const
	Locks the file for writing.
virtual void	unlockForWriting () const
	Unlocks the file for writing.
virtual bool	isLocked () const
	Tells whether the file is locked.
virtual time_t	getLastChangeTime () const
	Returns the latest change time of this embedded file.
virtual Ceylan::System::Size	read (Ceylan::Byte *buffer, Ceylan::System::Size maxLength)
	Reads up to maxLength bytes from this file to specified buffer.
virtual Ceylan::System::Size	write (const std::string &message)
	Writes message to this file.
virtual Ceylan::System::Size	write (const Ceylan::Byte *buffer, Ceylan::System::Size maxLength)
	Writes up to maxLength bytes from the specified buffer to this file.
virtual Ceylan::System::Position	tell ()
	Determines current position within this embedded file.
virtual void	seek (Ceylan::System::Position targetPosition)
	Seeks to specified position within this embedded file.
virtual Ceylan::System::Size	size () const
	Returns the file size, in bytes.
virtual void	serialize (PHYSFS_File &handle)
	Sends the file content to the fd PhysicsFS handle stream.
PHYSFS_File &	getPhysicsFSHandle () const
	Returns the stream id, its PhysicsFS handle.
virtual Ceylan::System::StreamID	getStreamID () const
	Returns this file's ID.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static void	CypherBuffer (Ceylan::Byte *buffer, Ceylan::System::Size size)
	Cyphers specified buffer.
static void	DecypherBuffer (Ceylan::Byte *buffer, Ceylan::System::Size size)
	Decyphers specified buffer.
static EmbeddedFile &	Create (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.
static EmbeddedFile &	Open (const std::string &filename, Ceylan::System::OpeningFlag openFlag=Ceylan::System::File::OpenToReadBinary)
	Returns an EmbeddedFile reference on specified already-existing file, in platform-independent notation, which will be opened with specified settings.
Protected Member Functions
	EmbeddedFile (const std::string &name, Ceylan::System::OpeningFlag openFlag=Ceylan::System::File::CreateToWriteBinary, Ceylan::System::PermissionFlag permissionFlag=Ceylan::System::File::OwnerReadWrite)
	Constructs an Embedded file reference object.
virtual Ceylan::System::FileSystemManager &	getCorrespondingFileSystemManager () const
	Returns the embedded filesystem manager.
virtual void	reopen ()
	Tries to reopen file.
virtual std::string	interpretState () const
	Interprets the current state of this file.
Private Member Functions
	EmbeddedFile (const EmbeddedFile &source)
	Copy constructor made private to ensure that it will be never called.
EmbeddedFile &	operator= (const EmbeddedFile &source)
	Assignment operator made private to ensure that it will be never called.
Static Private Member Functions
static void	FromHandletoHandle (PHYSFS_File &from, PHYSFS_File &to, Ceylan::System::Size length)
	Transfers bytes from a PhysicsFS handle to another.
Private Attributes
PHYSFS_File *	_physfsHandle
	Internal PhysicsFS handle.
bool	_cypher
	Tells whether reads and writes to this file should be cyphered.

Detailed Description

Encapsulates embedded files, i.e.

files in a virtual filesystem stored in an actual standard file, as provided by the PhysicsFS back-end.

See also:: http://icculus.org/physfs/

Note:: All files are managed in binary mode only. Reads and writes will be cyphered, depending on the filesystem manager setting.

Actual files should be created and opened with respectively the File::Create and File::Open factories, that allow the user program to be cross-platform by hiding each filesystem-related per-platform specificity.

Definition at line 81 of file OSDLEmbeddedFile.h.

Constructor & Destructor Documentation

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

Destroys the embedded file reference object, does not remove the file itself.

Note:: Will close automatically the file if needed.

To remove the file from disk, use remove().

See also:: remove

Definition at line 107 of file OSDLEmbeddedFile.cc.

References close(), and isOpen().

OSDL::EmbeddedFile::EmbeddedFile	(	const std::string &	name,
		Ceylan::System::OpeningFlag	openFlag = `Ceylan::System::File::CreateToWriteBinary`,
		Ceylan::System::PermissionFlag	permissionFlag = `Ceylan::System::File::OwnerReadWrite`
	)			`[explicit, protected]`

Constructs an Embedded file reference object.

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:

	name	the name of the file.
	openFlag	the flag describing the opening mode.
	permissionFlag	the flag describing the requested permissions, if this file is to be created. Otherwise (if the file already exists), this parameter is ignored.

See also:: OpeningFlag, PermissionFlag

Note:: If not specifically set, the file is open in text mode: one should not forget to add the Binary flag. The mistake can be detected when basic read() returns less than the requested size, or when readExactLength() never terminates.; This constructor should not be called directly, the File factories (File::Create and File::Open) should be used instead, as they allow to write code really independant from the running platform, not having to choose between the per-platform constructors.

Exceptions:

FileManagementException

if the operation failed.

OSDL::EmbeddedFile::EmbeddedFile ( const EmbeddedFile & 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

bool EmbeddedFile::close ( ) [virtual]

Closes the file for read/write actions.

Note:: May fail if the operating system was buffering writes to the physical media, and, now forced to write those changes to physical media, cannot store the data for some reason. In such a case, the file handle stays open.

Returns:: true iff an operation had to be performed.

Exceptions:

Stream::CloseException

if the close operation failed.

Definition at line 159 of file OSDLEmbeddedFile.cc.

References _physfsHandle, OSDL::EmbeddedFileSystemManager::GetBackendLastError(), and isOpen().

Referenced by OSDL::EmbeddedFileSystemManager::copyFile(), and ~EmbeddedFile().

static EmbeddedFile& OSDL::EmbeddedFile::Create	(	const std::string &	filename,
		Ceylan::System::OpeningFlag	createFlag = `Ceylan::System::File::CreateToWriteBinary`,
		Ceylan::System::PermissionFlag	permissionFlag = `Ceylan::System::File::OwnerReadWrite`
	)			`[static]`

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 to be created.
	createFlag	the flag describing the creation mode. Only binary access is performed.
	permissionFlag	the flag describing the requested permissions.

See also:: OpeningFlag, PermissionFlag

Note:: This EmbeddedFile factory is only a helper method. Ceylan users should only use File::Create instead.

Exceptions:

FileException,including

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

Referenced by OSDL::EmbeddedFileSystemManager::copyFile(), and saveAs().

void EmbeddedFile::CypherBuffer	(	Ceylan::Byte *	buffer,
		Ceylan::System::Size	size
	)			`[static]`

Cyphers specified buffer.

Parameters:

	buffer	the buffer to update.
	size	the number of bytes to cypher.

Exceptions:

EmbeddedFileException

if the operation failed.

Note:: Public, so that very specific tools can call it (ex: cypherOSDLFile).

Definition at line 592 of file OSDLEmbeddedFile.cc.

References OSDL::EmbeddedFileSystemManager::GetXORByte().

static void OSDL::EmbeddedFile::DecypherBuffer	(	Ceylan::Byte *	buffer,
		Ceylan::System::Size	size
	)			`[static]`

Decyphers specified buffer.

Parameters:

	buffer	the buffer to update.
	size	the number of bytes to decypher.

Exceptions:

EmbeddedFileException

if the operation failed.

Note:: Public, so that very specific tools can call it (ex: cypherOSDLFile).

static void OSDL::EmbeddedFile::FromHandletoHandle	(	PHYSFS_File &	from,
		PHYSFS_File &	to,
		Ceylan::System::Size	length
	)			`[static, private]`

Transfers bytes from a PhysicsFS handle to another.

Parameters:

	from	the source PhysicsFS handle.
	to	the target PhysicsFS handle.
	length	the length of the transfer, in bytes.

Note:: Currently not implemented.

Exceptions:

EmbeddedFileException

in all cases.

Referenced by serialize().

FileSystemManager & EmbeddedFile::getCorrespondingFileSystemManager ( ) const [protected, virtual]

Returns the embedded filesystem manager.

Exceptions:

FileDelegatingException

if the operation failed.

Definition at line 731 of file OSDLEmbeddedFile.cc.

References OSDL::EmbeddedFileSystemManager::GetEmbeddedFileSystemManager().

Referenced by getLastChangeTime().

time_t EmbeddedFile::getLastChangeTime ( ) const [virtual]

Returns the latest change time of this embedded file.

Exceptions:

FileLastChangeTimeRequestFailed

if the operation failed, or is not supported.

Definition at line 281 of file OSDLEmbeddedFile.cc.

References getCorrespondingFileSystemManager().

PHYSFS_File & EmbeddedFile::getPhysicsFSHandle ( ) const

Returns the stream id, its PhysicsFS handle.

Exceptions:

EmbeddedFileException

if the operation failed or if the PhysicsFS handle feature is not available.

Definition at line 569 of file OSDLEmbeddedFile.cc.

Referenced by getStreamID().

StreamID EmbeddedFile::getStreamID ( ) const [virtual]

Returns this file's ID.

Returns:: the StreamID or -1 if nothing appropriate can be returned with the available features.

Definition at line 625 of file OSDLEmbeddedFile.cc.

References getPhysicsFSHandle().

std::string EmbeddedFile::interpretState ( ) const [protected, virtual]

Interprets the current state of this file.

Definition at line 818 of file OSDLEmbeddedFile.cc.

bool EmbeddedFile::isLocked ( ) const [virtual]

Tells whether the file is locked.

Returns:: true if the lock feature is available and the file is locked, otherwise returns false, i.e. if the file is locked or if the lock feature is not available.

Definition at line 272 of file OSDLEmbeddedFile.cc.

bool EmbeddedFile::isOpen ( ) const [virtual]

Returns true iff this file is open.

Definition at line 142 of file OSDLEmbeddedFile.cc.

References _physfsHandle.

Referenced by close(), and ~EmbeddedFile().

void EmbeddedFile::lockForReading ( ) const [virtual]

Locks the file for reading.

No locking offered by PhysicsFS.

Exceptions:

FileReadLockingFailed

if the operation failed or if the file lock feature is not available.

Definition at line 232 of file OSDLEmbeddedFile.cc.

void EmbeddedFile::lockForWriting ( ) const [virtual]

Locks the file for writing.

Exceptions:

FileWriteLockingFailed

if the operation failed or if the file lock feature is not available.

Definition at line 252 of file OSDLEmbeddedFile.cc.

static EmbeddedFile& OSDL::EmbeddedFile::Open	(	const std::string &	filename,
		Ceylan::System::OpeningFlag	openFlag = `Ceylan::System::File::OpenToReadBinary`
	)			`[static]`

Returns an EmbeddedFile reference on specified already-existing file, in platform-independent notation, which will be opened with specified settings.

If the file is open for writing or appending, then the write directory will be taken as the root of the writable filesystem.

When a file is opened for writing, the specifiedfile is created if it does not exist. Otherwise it is truncated to zero bytes, and the writing offset is set to the start.

When a file is opened for appending, the specified file is created if it does not exist. Otherwise the writing offset is set to the end of the file, so the first write will be the byte after the end.

If the file is open for reading, then the search path will be checked one at a time until a matching file is found. The reading offset is set to the first byte of the file.

Parameters:

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

See also:: OpeningFlag

Note:: This EmbeddedFile factory is only a helper method. OSDL users should only use File::Open instead.

Exceptions:

FileException,including

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

Note that, depending on the archive type, opening the same file more than once may or may not work (read content apparently could be scrambled when opened twice).

Referenced by OSDL::EmbeddedFileSystemManager::copyFile().

EmbeddedFile& OSDL::EmbeddedFile::operator= ( const EmbeddedFile & 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.

virtual Ceylan::System::Size OSDL::EmbeddedFile::read	(	Ceylan::Byte *	buffer,
		Ceylan::System::Size	maxLength
	)			`[virtual]`

Reads up to maxLength bytes from this file to specified buffer.

The file must be opened for reading.

Parameters:

	buffer	the buffer where to store read bytes. Its size must be at least maxLength bytes.
	maxLength	the maximum number of bytes that should be read.

Returns:: The number of bytes actually read, which should be maxLength or lower.

Exceptions:

InputStream::ReadFailedException

if a read error occurred. Note that this is not a child class of FileException, as it comes from an inherited interface.

Note:: If cyphering is enabled, it will be transparently managed.

Referenced by OSDL::EmbeddedFileSystemManager::copyFile().

void EmbeddedFile::reopen ( ) [protected, virtual]

Tries to reopen file.

Exceptions:

FileOpeningFailed

if the operation failed.

Definition at line 753 of file OSDLEmbeddedFile.cc.

References OSDL::EmbeddedFileSystemManager::GetBackendLastError().

void EmbeddedFile::saveAs ( const std::string & newName ) [virtual]

Saves the file under a new name.

Parameters:

newName

the name of the newly copied file.

Note:: Currently not implemented.

Exceptions:

FileException

in all cases.

Definition at line 199 of file OSDLEmbeddedFile.cc.

References _physfsHandle, Create(), and serialize().

virtual void OSDL::EmbeddedFile::seek ( Ceylan::System::Position targetPosition ) [virtual]

Seeks to specified position within this embedded file.

Parameters:

targetPosition

this position corresponds to the number of bytes from start of file to seek to.

Exceptions:

FileException

if the operation failed.

void EmbeddedFile::serialize ( PHYSFS_File & handle ) [virtual]

Sends the file content to the fd PhysicsFS handle stream.

Exceptions:

EmbeddedFileException

if the operation failed or if the PhysicsFS handle feature is not available.

Definition at line 559 of file OSDLEmbeddedFile.cc.

References FromHandletoHandle(), and size().

Referenced by saveAs().

Size EmbeddedFile::size ( ) const [virtual]

Returns the file size, in bytes.

See also:: GetSize

Exceptions:

FileException,including

FileLookupFailed if the file metadata could not be accessed or if the operation is not supported on this platform, and FileDelegatingException if the corresponding filesystem manager could not be used as expected.

Definition at line 522 of file OSDLEmbeddedFile.cc.

References OSDL::EmbeddedFileSystemManager::GetBackendLastError().

Referenced by serialize().

Position EmbeddedFile::tell ( ) [virtual]

Determines current position within this embedded file.

Returns:: offset in bytes from start of file.

Exceptions:

FileException

if the operation failed.

Definition at line 451 of file OSDLEmbeddedFile.cc.

References _physfsHandle, and OSDL::EmbeddedFileSystemManager::GetBackendLastError().

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

Returns an 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 645 of file OSDLEmbeddedFile.cc.

void EmbeddedFile::unlockForReading ( ) const [virtual]

Unlocks the file for reading.

Exceptions:

FileReadUnlockingFailed

if the operation failed or if the file lock feature is not available.

Definition at line 242 of file OSDLEmbeddedFile.cc.

void EmbeddedFile::unlockForWriting ( ) const [virtual]

Unlocks the file for writing.

Exceptions:

FileWriteUnlockingFailed

if the operation failed or if the file lock feature is not available.

Definition at line 262 of file OSDLEmbeddedFile.cc.

virtual Ceylan::System::Size OSDL::EmbeddedFile::write	(	const Ceylan::Byte *	buffer,
		Ceylan::System::Size	maxLength
	)			`[virtual]`

Writes up to maxLength bytes from the specified buffer to this file.

Parameters:

buffer

the buffer where to find bytes that must be written to this file. Its size must be at least maxLength bytes.

Returns:: The number of bytes actually written, which should be equal to maxLength.

Exceptions:

OutputStream::WriteFailedException

if a write error occurred. Note that this is not a child class of FileException, as it comes from an inherited interface.

Note:: If cyphering is enabled, it will be transparently managed.

Size EmbeddedFile::write ( const std::string & message ) [virtual]

Writes message to this file.

The file must be opened for writing.

Parameters:

message

the message to write to this file.

Returns:: The number of bytes actually written, which should be equal to the size of the string or lower.

Exceptions:

OutputStream::WriteFailedException

if a write error occurred. Note that this is not a child class of FileException, as it comes from an inherited interface.

Note:: If cyphering is enabled, it will be transparently managed.

Definition at line 385 of file OSDLEmbeddedFile.cc.

Referenced by OSDL::EmbeddedFileSystemManager::copyFile().

Member Data Documentation

bool OSDL::EmbeddedFile::_cypher [private]

Tells whether reads and writes to this file should be cyphered.

Definition at line 634 of file OSDLEmbeddedFile.h.

PHYSFS_File* OSDL::EmbeddedFile::_physfsHandle [private]

Internal PhysicsFS handle.

Definition at line 626 of file OSDLEmbeddedFile.h.

Referenced by close(), isOpen(), saveAs(), and tell().

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

OSDL::EmbeddedFile Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation