PFile Class Reference

This class represents a disk file. More...

#include <file.h>

Inheritance diagram for PFile:

List of all members.

Construction
enum	OpenMode { ReadOnly, WriteOnly, ReadWrite }
	When a file is opened, it may restrict the access available to operations on the object instance. More...
enum	OpenOptions {   ModeDefault = -1, MustExist = 0, Create = 1, Truncate = 2,   Exclusive = 4, Temporary = 8, DenySharedRead = 16, DenySharedWrite = 32 }
	When a file is opened, a number of options may be associated with the open file. More...
	PFile ()
	Create a file object but do not open it.
	PFile (OpenMode mode, int opts=ModeDefault)
	Create a unique temporary file name, and open the file in the specified mode and using the specified options.
	PFile (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
	Create a file object with the specified name and open it in the specified mode and with the specified options.
	~PFile ()
	Close the file on destruction.
File channel functions
enum	FilePositionOrigin { Start = SEEK_SET, Current = SEEK_CUR, End = SEEK_END }
	Options for the origin in setting the file position. More...
const PFilePath &	GetFilePath () const
	Get the full path name of the file.
void	SetFilePath (const PString &path)
	Set the full path name of the file.
virtual PBoolean	Open (OpenMode mode=ReadWrite, int opts=ModeDefault)
	Open the current file in the specified mode and with the specified options.
virtual PBoolean	Open (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
	Open the specified file name in the specified mode and with the specified options.
virtual off_t	GetLength () const
	Get the current size of the file.
virtual PBoolean	SetLength (off_t len)
	Set the size of the file, padding with 0 bytes if it would require expanding the file, or truncating it if being made shorter.
virtual PBoolean	SetPosition (off_t pos, FilePositionOrigin origin=Start)
	Set the current active position in the file for the next read or write operation.
virtual off_t	GetPosition () const
	Get the current active position in the file for the next read or write operation.
PBoolean	IsEndOfFile () const
	Determine if the current file position is at the end of the file.
PBoolean	GetInfo (PFileInfo &info)
	Get information (eg protection, timestamps) on the current file.
PBoolean	SetPermissions (int permissions)
	Set permissions on the current file.
static PBoolean	GetInfo (const PFilePath &name, PFileInfo &info)
	Get information (eg protection, timestamps) on the specified file.
static PBoolean	SetPermissions (const PFilePath &name, int permissions)
	Set permissions on the specified file.
File manipulation functions
PBoolean	Exists () const
	Check for file existance.
PBoolean	Access (OpenMode mode)
	Check for file access modes.
PBoolean	Remove (PBoolean force=false)
	Delete the current file.
PBoolean	Rename (const PString &newname, PBoolean force=false)
	Change the current files name.
PBoolean	Copy (const PFilePath &newname, PBoolean force=false)
	Make a copy of the current file.
PBoolean	Move (const PFilePath &newname, PBoolean force=false)
	Move the current file.
static PBoolean	Exists (const PFilePath &name)
	Check for file existance.
static PBoolean	Access (const PFilePath &name, OpenMode mode)
	Check for file access modes.
static PBoolean	Remove (const PFilePath &name, PBoolean force=false)
	Delete the specified file.
static PBoolean	Remove (const PString &name, PBoolean force=false)
static PBoolean	Rename (const PFilePath &oldname, const PString &newname, PBoolean force=false)
	Change the specified files name.
static PBoolean	Copy (const PFilePath &oldname, const PFilePath &newname, PBoolean force=false)
	Make a copy of the specified file.
static PBoolean	Move (const PFilePath &oldname, const PFilePath &newname, PBoolean force=false)
	Move the specified file.
Public Member Functions
Overrides from class PObject
Comparison	Compare (const PObject &obj) const
	Determine the relative rank of the two objects.
Overrides from class PChannel
virtual PString	GetName () const
	Get the platform and I/O channel type name of the channel.
virtual PBoolean	Read (void *buf, PINDEX len)
	Low level read from the file channel.
virtual PBoolean	Write (const void *buf, PINDEX len)
	Low level write to the file channel.
virtual PBoolean	Close ()
	Close the file channel.
Protected Attributes
PFilePath	path
	The fully qualified path name for the file.
PBoolean	removeOnClose
	File is to be removed when closed.

---

Detailed Description

This class represents a disk file.

This is a particular type of I/O channel that has certain attributes. All platforms have a disk file, though exact details of naming convertions etc may be different.

The basic model for files is that they are a named sequence of bytes that persists within a directory structure. The transfer of data to and from the file is made at a current position in the file. This may be set to random locations within the file.

---

Member Enumeration Documentation

enum PFile::FilePositionOrigin

Options for the origin in setting the file position.

Enumerator:

Start	Set position relative to start of file.
Current	Set position relative to current file position.
End	Set position relative to end of file.

enum PFile::OpenMode

When a file is opened, it may restrict the access available to operations on the object instance.

A value from this enum is passed to the Open() function to set the mode.

Enumerator:

ReadOnly	File can be read but not written.
WriteOnly	File can be written but not read.
ReadWrite	File can be both read and written.

enum PFile::OpenOptions

When a file is opened, a number of options may be associated with the open file.

These describe what action to take on opening the file and what to do on closure. A value from this enum is passed to the Open() function to set the options.

The ModeDefault option will use the following values:

• ReadOnly MustExist
• WriteOnly Create | Truncate
• ReadWrite Create

Enumerator:

ModeDefault	File options depend on the OpenMode parameter.
MustExist	File open fails if file does not exist.
Create	File is created if it does not exist.
Truncate	File is set to zero length if it already exists.
Exclusive	File open fails if file already exists.
Temporary	File is temporary and is to be deleted when closed.
DenySharedRead	File may not be read by another process.
DenySharedWrite	File may not be written by another process.

---

Constructor & Destructor Documentation

PFile::PFile

(

)

Create a file object but do not open it.

It does not initially have a valid file name. However, an attempt to open the file using the Open() function will generate a unique temporary file.

PFile::PFile	(	OpenMode	mode,
		int	opts = ModeDefault
	)

Create a unique temporary file name, and open the file in the specified mode and using the specified options.

Note that opening a new, unique, temporary file name in ReadOnly mode will always fail. This would only be usefull in a mode and options that will create the file.

The PChannel::IsOpen() function may be used after object construction to determine if the file was successfully opened.

Parameters:

mode	Mode in which to open the file.
opts	OpenOptions enum# for open operation.

PFile::PFile	(	const PFilePath &	name,
		OpenMode	mode = ReadWrite,
		int	opts = ModeDefault
	)

Create a file object with the specified name and open it in the specified mode and with the specified options.

The PChannel::IsOpen() function may be used after object construction to determine if the file was successfully opened.

Parameters:

name	Name of file to open.
mode	Mode in which to open the file.
opts	OpenOptions enum# for open operation.

PFile::~PFile

(

)

Close the file on destruction.

---

Member Function Documentation

PBoolean PFile::Access

(

OpenMode

mode

)

Check for file access modes.

Determine if the file path specification associated with the instance of the object may be opened in the specified mode. This would check the current access rights to the file for the mode. For example, for a file that is read only, using mode == ReadWrite would return false but mode == ReadOnly would return true.

Returns:

true if a file open would succeed.

Parameters:

mode	Mode in which the file open would be done.

static PBoolean PFile::Access	(	const PFilePath &	name,
		OpenMode	mode
	)			[static]

Check for file access modes.

Determine if the file specified may be opened in the specified mode. This would check the current access rights to the file for the mode. For example, for a file that is read only, using mode == ReadWrite would return false but mode == ReadOnly would return true.

Returns:

true if a file open would succeed.

Parameters:

name	Name of file to have its access checked.
mode	Mode in which the file open would be done.

virtual PBoolean PFile::Close

(

)

[virtual]

Close the file channel.

Returns:

true if close was OK.

Reimplemented from PChannel.

Reimplemented in PWAVFile.

Comparison PFile::Compare

(

const PObject &

obj

)

const [virtual]

Determine the relative rank of the two objects.

This is essentially the string comparison of the PFilePath names of the files.

Returns:

relative rank of the file paths.

Parameters:

obj	Other file to compare against.

Reimplemented from PChannel.

Reimplemented in PMemoryFile.

PBoolean PFile::Copy	(	const PFilePath &	newname,
		PBoolean	force = false
	)

Make a copy of the current file.

Returns:

true if the file was renamed.

Parameters:

newname	New name for the file.
force	Delete file if a destination exists with the same name.

static PBoolean PFile::Copy	(	const PFilePath &	oldname,
		const PFilePath &	newname,
		PBoolean	force = false
	)			[static]

Make a copy of the specified file.

Returns:

true if the file was renamed.

Parameters:

oldname	Old name of the file.
newname	New name for the file.
force	Delete file if a destination exists with the same name.

PBoolean PFile::Exists

(

)

const

Check for file existance.

Determine if the file path specification associated with the instance of the object actually exists within the platforms file system.

Returns:

true if the file exists.

static PBoolean PFile::Exists

(

const PFilePath &

name

)

[static]

Check for file existance.

Determine if the file specified actually exists within the platforms file system.

Returns:

true if the file exists.

Parameters:

name	Name of file to see if exists.

const PFilePath& PFile::GetFilePath

(

)

const

Get the full path name of the file.

The PFilePath object describes the full file name specification for the particular platform.

Returns:

the name of the file.

PBoolean PFile::GetInfo

(

PFileInfo &

info

)

Get information (eg protection, timestamps) on the current file.

Returns:

true if the file info was retrieved.

static PBoolean PFile::GetInfo	(	const PFilePath &	name,
		PFileInfo &	info
	)			[static]

Get information (eg protection, timestamps) on the specified file.

Returns:

true if the file info was retrieved.

virtual off_t PFile::GetLength

(

)

const [virtual]

Get the current size of the file.

Returns:

length of file in bytes.

Reimplemented in PMemoryFile.

virtual PString PFile::GetName

(

)

const [virtual]

Get the platform and I/O channel type name of the channel.

For example, it would return the filename in PFile type channels.

Returns:

the name of the channel.

Reimplemented from PChannel.

virtual off_t PFile::GetPosition

(

)

const [virtual]

Get the current active position in the file for the next read or write operation.

Returns:

current file position relative to start of file.

Reimplemented in PMemoryFile, and PWAVFile.

PBoolean PFile::IsEndOfFile

(

)

const

Determine if the current file position is at the end of the file.

If this is true then any read operation will fail.

Returns:

true if at end of file.

PBoolean PFile::Move	(	const PFilePath &	newname,
		PBoolean	force = false
	)

Move the current file.

This will move the file from one position in the directory hierarchy to another position. The actual operation is platform dependent but the reslt is the same. For instance, for Unix, if the move is within a file system then a simple rename is done, if it is across file systems then a copy and a delete is performed.

Returns:

true if the file was moved.

Parameters:

newname	New path and name for the file.
force	Delete file if a destination exists with the same name.

static PBoolean PFile::Move	(	const PFilePath &	oldname,
		const PFilePath &	newname,
		PBoolean	force = false
	)			[static]

Move the specified file.

This will move the file from one position in the directory hierarchy to another position. The actual operation is platform dependent but the reslt is the same. For instance, for Unix, if the move is within a file system then a simple rename is done, if it is across file systems then a copy and a delete is performed.

Returns:

true if the file was moved.

Parameters:

oldname	Old path and name of the file.
newname	New path and name for the file.
force	Delete file if a destination exists with the same name.

virtual PBoolean PFile::Open	(	const PFilePath &	name,
		OpenMode	mode = ReadWrite,
		int	opts = ModeDefault
	)			[virtual]

Open the specified file name in the specified mode and with the specified options.

If the file object already has an open file then it is closed.

Note: if mode is StandardInput, StandardOutput or StandardError, then the name parameter is ignored.

Returns:

true if the file was successfully opened.

virtual PBoolean PFile::Open	(	OpenMode	mode = ReadWrite,
		int	opts = ModeDefault
	)			[virtual]

Open the current file in the specified mode and with the specified options.

If the file object already has an open file then it is closed.

If there has not been a filename attached to the file object (via SetFilePath(), the name parameter or a previous open) then a new unique temporary filename is generated.

Returns:

true if the file was successfully opened.

virtual PBoolean PFile::Read	(	void *	buf,
		PINDEX	len
	)			[virtual]

Low level read from the file channel.

The read timeout is ignored for file I/O. The GetLastReadCount() function returns the actual number of bytes read.

The GetErrorCode() function should be consulted after Read() returns false to determine what caused the failure.

Returns:

true indicates that at least one character was read from the channel. false means no bytes were read due to timeout or some other I/O error.

Parameters:

buf	Pointer to a block of memory to receive the read bytes.
len	Maximum number of bytes to read into the buffer.

Reimplemented from PChannel.

Reimplemented in PMemoryFile, and PWAVFile.

PBoolean PFile::Remove

(

PBoolean

force = false

)

Delete the current file.

If force is false and the file is protected against being deleted then the function fails. If force is true then the protection is ignored. What constitutes file deletion protection is platform dependent, eg on DOS is the Read Only attribute and on a Novell network it is a Delete trustee right. Some protection may not be able to overridden with the force parameter at all, eg on a Unix system and you are not the owner of the file.

Returns:

true if the file was deleted.

static PBoolean PFile::Remove	(	const PString &	name,
		PBoolean	force = false
	)			[static]

static PBoolean PFile::Remove	(	const PFilePath &	name,
		PBoolean	force = false
	)			[static]

Delete the specified file.

If force is false and the file is protected against being deleted then the function fails. If force is true then the protection is ignored. What constitutes file deletion protection is platform dependent, eg on DOS is the Read Only attribute and on a Novell network it is a Delete trustee right. Some protection may not be able to overridden with the force parameter at all, eg on a Unix system and you are not the owner of the file.

Returns:

true if the file was deleted.

PBoolean PFile::Rename	(	const PString &	newname,
		PBoolean	force = false
	)

Change the current files name.

This does not move the file in the directory hierarchy, it only changes the name of the directory entry.

The newname parameter must consist only of the file name part, as returned by the PFilePath::GetFileName() function. Any other file path parts will cause an error.

The first form uses the file path specification associated with the instance of the object. The name within the instance is changed to the new name if the function succeeds. The second static function uses an arbitrary file specified by name.

Returns:

true if the file was renamed.

Parameters:

newname	New name for the file.
force	Delete file if a destination exists with the same name.

static PBoolean PFile::Rename	(	const PFilePath &	oldname,
		const PString &	newname,
		PBoolean	force = false
	)			[static]

Change the specified files name.

This does not move the file in the directory hierarchy, it only changes the name of the directory entry.

The newname parameter must consist only of the file name part, as returned by the PFilePath::GetFileName() function. Any other file path parts will cause an error.

The first form uses the file path specification associated with the instance of the object. The name within the instance is changed to the new name if the function succeeds. The second static function uses an arbitrary file specified by name.

Returns:

true if the file was renamed.

Parameters:

oldname	Old name of the file.
newname	New name for the file.
force	Delete file if a destination exists with the same name.

void PFile::SetFilePath

(

const PString &

path

)

Set the full path name of the file.

The PFilePath object describes the full file name specification for the particular platform.

Parameters:

path	New file path.

virtual PBoolean PFile::SetLength

(

off_t

len

)

[virtual]

Set the size of the file, padding with 0 bytes if it would require expanding the file, or truncating it if being made shorter.

Returns:

true if the file size was changed to the length specified.

Reimplemented in PMemoryFile.

PBoolean PFile::SetPermissions

(

int

permissions

)

Set permissions on the current file.

Returns:

true if the file was renamed.

static PBoolean PFile::SetPermissions	(	const PFilePath &	name,
		int	permissions
	)			[static]

Set permissions on the specified file.

Returns:

true if the file was renamed.

virtual PBoolean PFile::SetPosition	(	off_t	pos,
		FilePositionOrigin	origin = Start
	)			[virtual]

Set the current active position in the file for the next read or write operation.

The pos variable is a signed number which is added to the specified origin. For origin == PFile::Start only positive values for pos are meaningful. For origin == PFile::End only negative values for pos are meaningful.

Returns:

true if the new file position was set.

Parameters:

pos	New position to set.
origin	Origin for position change.

virtual PBoolean PFile::Write	(	const void *	buf,
		PINDEX	len
	)			[virtual]

Low level write to the file channel.

The write timeout is ignored for file I/O. The GetLastWriteCount() function returns the actual number of bytes written.

The GetErrorCode() function should be consulted after Write() returns false to determine what caused the failure.

Returns:

true if at least len bytes were written to the channel.

Parameters:

buf	Pointer to a block of memory to write.
len	Number of bytes to write.

Reimplemented from PChannel.

Reimplemented in PMemoryFile, and PWAVFile.

---

Member Data Documentation

PFilePath PFile::path [protected]

The fully qualified path name for the file.

PBoolean PFile::removeOnClose [protected]

File is to be removed when closed.

---

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

• file.h

---