PTextFile Class Reference

A class representing a a structured file that is portable accross CPU architectures. More...

`#include <textfile.h>`

Inheritance diagram for PTextFile:

## Public Member Functions

Construction
| PTextFile ()
| Create a text file object but do not open it. More...
| PTextFile (OpenMode mode, int opts=ModeDefault)
| Create a unique temporary file name, and open the file in the specified mode and using the specified options. More...
| PTextFile (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
| Create a text file object with the specified name and open it in the specified mode and with the specified options. More...
Line I/O functions
PBoolean | ReadLine (PString &str)
| Read a line from the text file. More...
PBoolean | WriteLine (const PString &str)
| Read a line from the text file. More...
Public Member Functions inherited from PFile
Comparison | Compare (const PObject &obj) const
| Determine the relative rank of the two objects. More...
virtual PString | GetName () const
| Get the platform and I/O channel type name of the channel. More...
virtual PBoolean | Read (void *buf, PINDEX len)
| Low level read from the file channel. More...
virtual PBoolean | Write (const void *buf, PINDEX len)
| Low level write to the file channel. More...
virtual PBoolean | Close ()
| Close the file channel. More...
| PFile ()
| Create a file object but do not open it. More...
| 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. More...
| 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. More...
| ~PFile ()
| Close the file on destruction. More...
PBoolean | Exists () const
| Check for file existance. More...
PBoolean | Access (OpenMode mode)
| Check for file access modes. More...
PBoolean | Remove (PBoolean force=false)
| Delete the current file. More...
PBoolean | Rename (const PString &newname, PBoolean force=false)
| Change the current files name. More...
PBoolean | Copy (const PFilePath &newname, PBoolean force=false)
| Make a copy of the current file. More...
PBoolean | Move (const PFilePath &newname, PBoolean force=false)
| Move the current file. More...
const PFilePath & | GetFilePath () const
| Get the full path name of the file. More...
void | SetFilePath (const PString &path)
| Set the full path name of the file. More...
virtual PBoolean | Open (OpenMode mode=ReadWrite, int opts=ModeDefault)
| Open the current file in the specified mode and with the specified options. More...
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. More...
virtual off_t | GetLength () const
| Get the current size of the file. More...
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. More...
virtual PBoolean | SetPosition (off_t pos, FilePositionOrigin origin=Start)
| Set the current active position in the file for the next read or write operation. More...
virtual off_t | GetPosition () const
| Get the current active position in the file for the next read or write operation. More...
PBoolean | IsEndOfFile () const
| Determine if the current file position is at the end of the file. More...
PBoolean | GetInfo (PFileInfo &info)
| Get information (eg protection, timestamps) on the current file. More...
PBoolean | SetPermissions (int permissions)
| Set permissions on the current file. More...
Public Member Functions inherited from PChannel
PBoolean | SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
| Set error values to those specified. More...
| PChannel ()
| Create the channel. More...
| ~PChannel ()
| Close down the channel. More...
virtual PINDEX | HashFunction () const
| Calculate a hash value for use in sets and dictionaries. More...
virtual PBoolean | IsOpen () const
| Determine if the channel is currently open. More...
int | GetHandle () const
| Get the integer operating system handle for the channel. More...
virtual PChannel * | GetBaseReadChannel () const
| Get the base channel of channel indirection using PIndirectChannel. More...
virtual PChannel * | GetBaseWriteChannel () const
| Get the base channel of channel indirection using PIndirectChannel. More...
void | SetReadTimeout (const PTimeInterval &time)
| Set the timeout for read operations. More...
PTimeInterval | GetReadTimeout () const
| Get the timeout for read operations. More...
virtual PINDEX | GetLastReadCount () const
| Get the number of bytes read by the last Read() call. More...
virtual int | ReadChar ()
| Read a single 8 bit byte from the channel. More...
PBoolean | ReadBlock (void *buf, PINDEX len)
| Read len bytes into the buffer from the channel. More...
PString | ReadString (PINDEX len)
| Read `len` character into a string from the channel. More...
virtual PBoolean | ReadAsync (void *buf, PINDEX len)
| Begin an asynchronous read from channel. More...
virtual void | OnReadComplete (void *buf, PINDEX len)
| User callback function for when a `ReadAsync()` call has completed or timed out. More...
void | SetWriteTimeout (const PTimeInterval &time)
| Set the timeout for write operations to complete. More...
PTimeInterval | GetWriteTimeout () const
| Get the timeout for write operations to complete. More...
virtual PBoolean | Write (const void *buf, PINDEX len, const void *mark)
| Low level write to the channel with marker. More...
virtual PINDEX | GetLastWriteCount () const
| Get the number of bytes written by the last Write() call. More...
PBoolean | WriteChar (int c)
| Write a single character to the channel. More...
PBoolean | WriteString (const PString &str)
| Write a string to the channel. More...
virtual PBoolean | WriteAsync (const void *buf, PINDEX len)
| Begin an asynchronous write from channel. More...
virtual void | OnWriteComplete (const void *buf, PINDEX len)
| User callback function for when a WriteAsync() call has completed or timed out. More...
virtual PBoolean | Shutdown (ShutdownValue option)
| Close one or both of the data streams associated with a channel. More...
virtual bool | SetLocalEcho (bool localEcho)
| Set local echo mode. More...
virtual bool | FlowControl (const void *flowData)
| Flow Control information Pass data to the channel for flowControl determination. More...
PBoolean | SetBufferSize (PINDEX newSize)
| Set the iostream buffer size for reads and writes. More...
PBoolean | SendCommandString (const PString &command)
| Send a command meta-string. More...
void | AbortCommandString ()
| Abort a command string that is in progress. More...
Errors | GetErrorCode (ErrorGroup group=NumErrorGroups) const
| Get normalised error code. More...
int | GetErrorNumber (ErrorGroup group=NumErrorGroups) const
| Get OS errro code. More...
virtual PString | GetErrorText (ErrorGroup group=NumErrorGroups) const
| Get error message description. More...
virtual PBoolean | Read (const VectorOfSlice &slices)
| Low level scattered read from the channel. More...
virtual PBoolean | Write (const VectorOfSlice &slices)
| Low level scattered write to the channel. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Additional Inherited Members

Public Types inherited from PFile
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...
enum | FilePositionOrigin { Start = SEEK_SET, Current = SEEK_CUR, End = SEEK_END }
| Options for the origin in setting the file position. More...
Public Types inherited from PChannel
enum | PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }
enum | ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
enum | Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, NumNormalisedErrors }
| Normalised error codes. More...
enum | ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
| Error groups. More...
typedef std::vector< Slice > | VectorOfSlice
Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...
Static Public Member Functions inherited from PFile
static PBoolean | Exists (const PFilePath &name)
| Check for file existance. More...
static PBoolean | Access (const PFilePath &name, OpenMode mode)
| Check for file access modes. More...
static PBoolean | Remove (const PFilePath &name, PBoolean force=false)
| Delete the specified file. More...
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. More...
static PBoolean | Copy (const PFilePath &oldname, const PFilePath &newname, PBoolean force=false)
| Make a copy of the specified file. More...
static PBoolean | Move (const PFilePath &oldname, const PFilePath &newname, PBoolean force=false)
| Move the specified file. More...
static PBoolean | GetInfo (const PFilePath &name, PFileInfo &info)
| Get information (eg protection, timestamps) on the specified file. More...
static PBoolean | SetPermissions (const PFilePath &name, int permissions)
| Set permissions on the specified file. More...
Static Public Member Functions inherited from PChannel
static PBoolean | ConvertOSError (int libcReturnValue, Errors &lastError, int &osError)
| Convert an operating system error into platform independent error. More...
static PString | GetErrorText (Errors lastError, int osError=0)
| Get error message description. More...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Protected Member Functions inherited from PChannel
| PChannel (const PChannel &)
PChannel & | operator= (const PChannel &)
virtual PBoolean | ConvertOSError (int libcReturnValue, ErrorGroup group=LastGeneralError)
| Convert an operating system error into platform independent error. More...
int | ReadCharWithTimeout (PTimeInterval &timeout)
| Read a character with specified timeout. More...
PBoolean | ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
PBoolean | PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)
int | PXClose ()
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...
Protected Attributes inherited from PFile
PFilePath | path
| The fully qualified path name for the file. More...
PBoolean | removeOnClose
| File is to be removed when closed. More...
Protected Attributes inherited from PChannel
int | os_handle
| The operating system file handle return by standard open() function. More...
Errors | lastErrorCode [NumErrorGroups+1]
| The platform independant error code. More...
int | lastErrorNumber [NumErrorGroups+1]
| The operating system error number (eg as returned by errno). More...
PINDEX | lastReadCount
| Number of byte last read by the Read() function. More...
PINDEX | lastWriteCount
| Number of byte last written by the Write() function. More...
PTimeInterval | readTimeout
| Timeout for read operations. More...
PTimeInterval | writeTimeout
| Timeout for write operations. More...
PString | channelName
PMutex | px_threadMutex
PXBlockType | px_lastBlockType
PThread * | px_readThread
PThread * | px_writeThread
PMutex | px_writeMutex
PThread * | px_selectThread [3]
PMutex | px_selectMutex [3]

## Detailed Description

A class representing a a structured file that is portable accross CPU architectures.

Essentially this will normalise the end of line character which differs fromplatform to platform.

## Constructor & Destructor Documentation

PTextFile::PTextFile | ( |  | ) |

Create a text 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 `PFile::Open()` function will generate a unique temporary file.

PTextFile::PTextFile | ( | 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.

PTextFile::PTextFile | ( | const PFilePath & | name,
|  | OpenMode | mode = `ReadWrite`,
|  | int | opts = `ModeDefault`
| ) |  |

Create a text 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.

## Member Function Documentation

PBoolean PTextFile::ReadLine | ( | PString & | str | ) |

Read a line from the text file.

What constitutes an end of line in the file is platform dependent.

Use the `PChannel::GetLastError()` function to determine if there was some error other than end of file.

Returns
  true if successful, false if at end of file or a read error.

Parameters

  str | String into which line of text is read.

PBoolean PTextFile::WriteLine | ( | const PString & | str | ) |

Read a line from the text file.

What constitutes an end of line in the file is platform dependent.

Use the `PChannel::GetLastError()` function to determine the failure mode.

Returns
  true if successful, false if an error occurred.

Parameters

  str | String to write with end of line terminator.

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

- textfile.h