# 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:

List of all members.

## 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.
void | SetStructure (Element *structure, PINDEX numElements)
| Set the structure of each record in the file.

## Public Member Functions

Construction
| PStructuredFile ()
| Create a structured file object but do not open it.
| PStructuredFile (OpenMode mode, int opts=ModeDefault)
| Create a unique temporary file name, and open the file in the specified mode and using the specified options.
| PStructuredFile (const PFilePath &name, OpenMode mode=ReadWrite, int opts=ModeDefault)
| Create a structured file object with the specified name and open it in the specified mode and with the specified options.
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.
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.

## Protected Attributes

PINDEX | structureSize
| Number of bytes in structure.
Element * | structure
| Array of elements in the structure.
PINDEX | numElements
| Number of elements in the array.

## Classes

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

## 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,
|  | 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.

PStructuredFile::PStructuredFile | ( | const PFilePath & | name,
|  | OpenMode | mode = `ReadWrite`,
|  | int | 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.

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.

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

- sfile.h