PFile Class Reference

#include <file.h>

Inheritance diagram for PFile:
PChannel PObject PMemoryFile PStructuredFile PTextFile PWAVFile

List of all members.

Public Member Functions

Overrides from class PObject

Comparison Compare (const PObject &obj) const
Overrides from class PChannel

virtual PString GetName () const
virtual PBoolean Read (void *buf, PINDEX len)
virtual PBoolean Write (const void *buf, PINDEX len)
virtual PBoolean Close ()

Protected Attributes

PFilePath path
 The fully qualified path name for the file.
PBoolean removeOnClose
 File is to be removed when closed.

Construction



enum  OpenMode { ReadOnly, WriteOnly, ReadWrite }
enum  OpenOptions {
  ModeDefault = -1, MustExist = 0, Create = 1, Truncate = 2,
  Exclusive = 4, Temporary = 8, DenySharedRead = 16, DenySharedWrite = 32
}
 PFile ()
 PFile (OpenMode mode, int opts=ModeDefault)
 PFile (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
 ~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 PFilePathGetFilePath () const
void SetFilePath (const PString &path)
virtual PBoolean Open (OpenMode mode=ReadWrite, int opts=ModeDefault)
virtual PBoolean Open (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
virtual off_t GetLength () const
virtual PBoolean SetLength (off_t len)
virtual PBoolean SetPosition (off_t pos, FilePositionOrigin origin=Start)
virtual off_t GetPosition () const
PBoolean IsEndOfFile () const
PBoolean GetInfo (PFileInfo &info)
PBoolean SetPermissions (int permissions)
static PBoolean GetInfo (const PFilePath &name, PFileInfo &info)
static PBoolean SetPermissions (const PFilePath &name, int permissions)

File manipulation functions



PBoolean Exists () const
PBoolean Access (OpenMode mode)
PBoolean Remove (PBoolean force=PFalse)
PBoolean Rename (const PString &newname, PBoolean force=PFalse)
PBoolean Copy (const PFilePath &newname, PBoolean force=PFalse)
PBoolean Move (const PFilePath &newname, PBoolean force=PFalse)
static PBoolean Exists (const PFilePath &name)
static PBoolean Access (const PFilePath &name, OpenMode mode)
static PBoolean Remove (const PFilePath &name, PBoolean force=PFalse)
static PBoolean Remove (const PString &name, PBoolean force=PFalse)
static PBoolean Rename (const PFilePath &oldname, const PString &newname, PBoolean force=PFalse)
static PBoolean Copy (const PFilePath &oldname, const PFilePath &newname, PBoolean force=PFalse)
static PBoolean Move (const PFilePath &oldname, const PFilePath &newname, PBoolean force=PFalse)

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

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.

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.

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: {tabular}{rr} Mode & Options \ ReadOnly# & MustExist# \ WriteOnly# & Create | Truncate# \ ReadWrite# & Create# \ {tabular}

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

PINLINE 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.

References PChannel::os_handle, PFalse, and removeOnClose.

PINLINE 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.

References Open(), PChannel::os_handle, PFalse, and removeOnClose.

PINLINE 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.

References Open(), PChannel::os_handle, PFalse, and removeOnClose.

PFile::~PFile (  ) 

Close the file on destruction.


Member Function Documentation

PINLINE 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 PFalse but mode == ReadOnly would return PTrue.

Returns:
PTrue if a file open would succeed.
Parameters:
mode Mode in which the file open would be done.

References Access(), PChannel::ConvertOSError(), and path.

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 PFalse but mode == ReadOnly would return PTrue.

Returns:
PTrue 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.

Referenced by Access().

virtual PBoolean PFile::Close (  )  [virtual]

Close the file channel.

Returns:
PTrue if close was OK.

Reimplemented from PChannel.

Reimplemented in PWAVFile.

Referenced by Remove().

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.

PINLINE PBoolean PFile::Copy ( const PFilePath newname,
PBoolean  force = PFalse 
)

Make a copy of the current file.

Returns:
PTrue if the file was renamed.
Parameters:
newname New name for the file.
force Delete file if a destination exists with the same name.

References PChannel::ConvertOSError(), Copy(), and path.

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

Make a copy of the specified file.

Returns:
PTrue 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.

Referenced by Copy().

PINLINE 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:
PTrue if the file exists.

References path.

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:
PTrue if the file exists.
Parameters:
name Name of file to see if exists.
PINLINE 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.

References path.

PINLINE PBoolean PFile::GetInfo ( PFileInfo info  ) 

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

Returns:
PTrue if the file info was retrieved.

References PChannel::ConvertOSError(), GetInfo(), and path.

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

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

Returns:
PTrue if the file info was retrieved.

Referenced by GetInfo().

virtual off_t PFile::GetLength (  )  const [virtual]

Get the current size of the file.

Returns:
length of file in bytes.

Reimplemented in PMemoryFile.

PINLINE 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.

References path.

PINLINE 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.

References _lseek, and PChannel::GetHandle().

PBoolean PFile::IsEndOfFile (  )  const

Determine if the current file position is at the end of the file. If this is PTrue then any read operation will fail.

Returns:
PTrue if at end of file.
PBoolean PFile::Move ( const PFilePath newname,
PBoolean  force = PFalse 
)

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:
PTrue 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 = PFalse 
) [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:
PTrue 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:
PTrue if the file was successfully opened.

Reimplemented in PWAVFile.

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:
PTrue if the file was successfully opened.

Reimplemented in PWAVFile.

Referenced by PFile(), and PTextFile::PTextFile().

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 PFalse to determine what caused the failure.

Returns:
PTrue indicates that at least one character was read from the channel. PFalse 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.

PINLINE PBoolean PFile::Remove ( PBoolean  force = PFalse  ) 

Delete the current file. If force# is PFalse and the file is protected against being deleted then the function fails. If force# is PTrue 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:
PTrue if the file was deleted.

References Close(), PChannel::ConvertOSError(), path, and Remove().

static PBoolean PFile::Remove ( const PString name,
PBoolean  force = PFalse 
) [static]
static PBoolean PFile::Remove ( const PFilePath name,
PBoolean  force = PFalse 
) [static]

Delete the specified file. If force# is PFalse and the file is protected against being deleted then the function fails. If force# is PTrue 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:
PTrue if the file was deleted.

Referenced by Remove().

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

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:
PTrue 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 = PFalse 
) [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:
PTrue 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:
PTrue if the file size was changed to the length specified.

Reimplemented in PMemoryFile.

PINLINE PBoolean PFile::SetPermissions ( int  permissions  ) 

Set permissions on the current file.

Returns:
PTrue if the file was renamed.

References PChannel::ConvertOSError(), path, and SetPermissions().

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

Set permissions on the specified file.

Returns:
PTrue if the file was renamed.

Referenced by SetPermissions().

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:
PTrue if the new file position was set.
Parameters:
pos New position to set.
origin Origin for position change.

Reimplemented in PMemoryFile, and PWAVFile.

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 PFalse to determine what caused the failure.

Returns:
PTrue 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.

Referenced by Access(), Copy(), Exists(), GetFilePath(), GetInfo(), GetName(), Remove(), and SetPermissions().

File is to be removed when closed.

Referenced by PFile().


The documentation for this class was generated from the following files:
Generated on Fri May 28 07:32:32 2010 for PTLib by  doxygen 1.6.3