PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Protected Attributes | List of all members
PStructuredFile Class Reference

A class representing a a structured file that is portable accross CPU architectures (as in the XDR protocol). More...

`#include <sfile.h>`

Inheritance diagram for PStructuredFile:
[legend]
Collaboration diagram for PStructuredFile:
[legend]

## Classes
struct | Element
| Elements in the structure definition. More...

## Public Member Functions
Construction
| PStructuredFile ()
| Create a structured file object but do not open it. More...
| PStructuredFile (OpenMode mode, OpenOptions opts=ModeDefault)
| Create a unique temporary file name, and open the file in the specified mode and using the specified options. More...
| PStructuredFile (const PFilePath &name, OpenMode mode=ReadWrite, OpenOptions opts=ModeDefault)
| Create a structured file object with the specified name and open it in the specified mode and with the specified options. More...
Structured I/O functions
PBoolean | Read (void *buffer)
| Read a sequence of bytes into the specified buffer, translating the structure according to the specification made in the `SetStructure()` function. More...
PBoolean | Write (const void *buffer)
| Write a sequence of bytes into the specified buffer, translating the structure according to the specification made in the `SetStructure()` function. 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 | Close ()
| Close the file channel. More...
| PFile ()
| Create a file object but do not open it. More...
| P_DECLARE_BITWISE_ENUM_EX (OpenOptions, 6,(MustExist, Create, Truncate, Exclusive, Temporary, DenySharedRead, DenySharedWrite), ModeDefault=-1)
| When a file is opened, a number of options may be associated with the open file. More...
| PFile (OpenMode mode, OpenOptions 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, OpenOptions 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, OpenOptions 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, OpenOptions 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...
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...
P_INT_PTR | 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...
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 *)
| 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...
| ~PChannel ()
| Close down the channel. 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 bool | ReadAsync (AsyncContext &context)
| Begin an asynchronous read from channel. More...
virtual void | OnReadComplete (AsyncContext &context)
| User callback function for when a `ReadAsync()` call has completed or timed out. More...
virtual bool | WriteAsync (AsyncContext &context)
| Begin an asynchronous write from channel. More...
virtual void | OnWriteComplete (AsyncContext &context)
| 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...
Public Member Functions inherited from PObject
unsigned | GetTraceContextIdentifier () const
| Get PTRACE context identifier. More...
void | SetTraceContextIdentifier (unsigned id)
void | GetTraceContextIdentifier (PObject &obj)
void | GetTraceContextIdentifier (PObject *obj)
void | SetTraceContextIdentifier (const PObject &obj)
void | SetTraceContextIdentifier (const PObject *obj)
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
template<class CLS >
CLS * | CloneAs () const
| As for Clone() but converts to specified type. 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...
__inline const PObject * | PTraceObjectInstance () const
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...

## Protected Attributes
PINDEX | structureSize
| Number of bytes in structure. More...
Element * | structure
| Array of elements in the structure. More...
PINDEX | numElements
| Number of elements in the array. 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
P_INT_PTR | 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
| Name of channel. More...
PMutex | px_threadMutex
PXBlockType | px_lastBlockType
PThread * | px_readThread
PThread * | px_writeThread
PMutex | px_writeMutex
PThread * | px_selectThread [3]
PMutex | px_selectMutex [3]
Protected Attributes inherited from PObject
unsigned | m_traceContextIdentifier

## Structure definition functions
enum | ElementType { Character, Integer16, Integer32, Integer64, Float32, Float64, Float80, NumElementTypes }
| All element types in a structure. More...
PINDEX | GetStructureSize ()
| Get the size of each structure in the file. More...
void | SetStructure (Element *structure, PINDEX numElements)
| Set the structure of each record in the file. 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 | 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 | Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, Unavailable, NumNormalisedErrors }
| Normalised error codes. More...
enum | ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
| Error groups. More...
typedef PNotifierTemplate < PChannel::AsyncContext & > | AsyncNotifier
enum | ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
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 PString | GetErrorText (Errors lastError, int osError=0)
| Get error message description. More...
static PBoolean | ConvertOSError (P_INT_PTR libcReturnValue, Errors &lastError, int &osError)
| Convert an operating system error into platform independent error. More...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static __inline const PObject * | PTraceObjectInstance (const char *)
static __inline const PObject * | PTraceObjectInstance (const PObject *obj)
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 (P_INT_PTR 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)
P_INT_PTR | GetOSHandleAsInt () const
int | PXClose ()
| PChannel ()
| Create the channel. More...
Friends inherited from PObject

## Detailed Description

A class representing a a structured file that is portable accross CPU architectures (as in the XDR protocol).

This differs from object serialisation in that the access is always to a disk file and is random access. It would primarily be used for database type applications.

## Member Enumeration Documentation

enum PStructuredFile::ElementType

All element types in a structure.

Enumerator
Character | Element is a single character.
Integer16 | Element is a 16 bit integer.
Integer32 | Element is a 32 bit integer.
Integer64 | Element is a 64 bit integer.
Float32 | Element is a 32 bit IEE floating point number.
Float64 | Element is a 64 bit IEE floating point number.
Float80 | Element is a 80 bit IEE floating point number.
NumElementTypes |

## Constructor & Destructor Documentation

PStructuredFile::PStructuredFile | ( |  | ) |

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

The initial structure size is one byte.

PStructuredFile::PStructuredFile | ( | OpenMode | mode,
|  | OpenOptions | 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.

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

Create a structured 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

PINDEX PStructuredFile::GetStructureSize | ( |  | ) |
| inline

Get the size of each structure in the file.

Returns
  number of bytes in a structure.

References structureSize.

PBoolean PStructuredFile::Read | ( | void * | buffer | ) |

Read a sequence of bytes into the specified buffer, translating the structure according to the specification made in the `SetStructure()` function.

Returns
  true if the structure was successfully read.

Parameters

  buffer | Pointer to structure to receive data.

void PStructuredFile::SetStructure | ( | Element * | structure,
|  | PINDEX | numElements
| ) |  |

Set the structure of each record in the file.

Parameters

  structure | Array of structure elements
  numElements | Number of structure elements in structure.

PBoolean PStructuredFile::Write | ( | const void * | buffer | ) |

Write a sequence of bytes into the specified buffer, translating the structure according to the specification made in the `SetStructure()` function.

Returns
  true if the structure was successfully written.

Parameters

  buffer | Pointer to structure to write data from.

## Member Data Documentation

PINDEX PStructuredFile::numElements
| protected

Number of elements in the array.

Element* PStructuredFile::structure
| protected

Array of elements in the structure.

PINDEX PStructuredFile::structureSize
| protected

Number of bytes in structure.

Referenced by GetStructureSize().

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

- sfile.h