class PFile: public PChannel

This class represents a disk file.

Inheritance:


Public

[more] Construction
[more] Overrides from class PObject
[more] Overrides from class PChannel
[more] File manipulation functions
[more] File channel functions

Protected Fields

[more]PFilePath path
The fully qualified path name for the file.
[more]BOOL removeOnClose
File is to be removed when closed.


Inherited from PChannel:

Public Methods

ostatic BOOL ConvertOSError( int libcReturnValue, Errors & lastError, int & osError )

Public

Information functions

Reading functions

Writing functions

Miscellaneous functions

Error functions

Protected Fields

oint os_handle
oErrors lastErrorCode[NumErrorGroups+1]
oint lastErrorNumber[NumErrorGroups+1]
oPINDEX lastReadCount
oPINDEX lastWriteCount
oPTimeInterval readTimeout
oPTimeInterval writeTimeout

Protected Methods

ovirtual BOOL ConvertOSError( int libcReturnValue, ErrorGroup group = LastGeneralError )
oBOOL SetErrorValues( Errors errorCode, int osError, ErrorGroup group = LastGeneralError )
oint ReadCharWithTimeout( PTimeInterval & timeout )


Inherited from PObject:

Public

Run Time Type functions

Comparison functions

I/O functions


Documentation

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.

o Construction

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

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

o ReadOnly
File can be read but not written.

o WriteOnly
File can be written but not read.

o ReadWrite
File can be both read and written.

oenum 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:
Mode Options
ReadOnly MustExist
WriteOnly Create | Truncate
ReadWrite Create

o ModeDefault
File options depend on the OpenMode parameter.

o MustExist
File open fails if file does not exist.

o Create
File is created if it does not exist.

o Truncate
File is set to zero length if it already exists.

o Exclusive
File open fails if file already exists.

o Temporary
File is temporary and is to be deleted when closed.

o DenySharedRead
File may not be read by another process.

o DenySharedWrite
File may not be written by another process.

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

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

o ~PFile()
Close the file on destruction.

o Overrides from class PObject

oComparison Compare( const PObject & obj ) const
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.

o Overrides from class PChannel

ovirtual PString GetName() const
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.

ovirtual BOOL Read( void * buf, PINDEX len )
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.

ovirtual BOOL Write( const void * buf, PINDEX len )
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.

ovirtual BOOL Close()
Close the file channel.
Returns:
TRUE if close was OK.

o File manipulation functions

ostatic BOOL Exists( const PFilePath & name )
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.

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

ostatic BOOL Access( const PFilePath & name, OpenMode mode )
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.

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

ostatic BOOL Remove( const PFilePath & name, BOOL force = FALSE )
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.

oBOOL Remove( BOOL 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.

ostatic BOOL Rename( const PFilePath & oldname, const PString & newname, BOOL force = FALSE )
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.

oBOOL Rename( const PString & newname, BOOL 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.

ostatic BOOL Copy( const PFilePath & oldname, const PFilePath & newname, BOOL force = FALSE )
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.

oBOOL Copy( const PFilePath & newname, BOOL 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.

ostatic BOOL Move( const PFilePath & oldname, const PFilePath & newname, BOOL force = FALSE )
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.

oBOOL Move( const PFilePath & newname, BOOL 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.

o File channel functions

oconst PFilePath& 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.

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

ovirtual BOOL Open( OpenMode mode = ReadWrite, int opts = ModeDefault )
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.

oBOOL Open( const PFilePath & name, OpenMode mode = ReadWrite, int opts = ModeDefault )
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.

ooff_t GetLength() const
Get the current size of the file.

Returns:
length of file in bytes.

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

Returns:
TRUE if the file size was changed to the length specified.

oenum FilePositionOrigin
Options for the origin in setting the file position.

o Start
Set position relative to start of file.

o Current
Set position relative to current file position.

o End
Set position relative to end of file.

oBOOL SetPosition( off_t pos, FilePositionOrigin origin = Start )
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.

ooff_t GetPosition() const
Get the current active position in the file for the next read or write operation.

Returns:
current file position relative to start of file.

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

ostatic BOOL GetInfo( const PFilePath & name, PFileInfo & info )
Get information (eg protection, timestamps) on the specified file.

Returns:
TRUE if the file info was retrieved.

oBOOL GetInfo( PFileInfo & info )
Get information (eg protection, timestamps) on the current file.

Returns:
TRUE if the file info was retrieved.

ostatic BOOL SetPermissions( const PFilePath & name, int permissions )
Set permissions on the specified file.

Returns:
TRUE if the file was renamed.

oBOOL SetPermissions( int permissions )
Set permissions on the current file.

Returns:
TRUE if the file was renamed.

oPFilePath path
The fully qualified path name for the file.

oBOOL removeOnClose
File is to be removed when closed.


Direct child classes:
PTextFile
PStructuredFile

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.