FX::QIODevice Class Reference
[File type i/o devicesWriting secure code]

#include <QIODevice.h>

Inheritance diagram for FX::QIODevice:

Inheritance graph
[legend]

List of all members.


Detailed Description

The abstract base class for all i/o classes in TnFOX (Qt compatible).

This is the base class for all TnFOX byte i/o classes. It provides a universal API for accessing all subclasses and while API compatible with Qt's QIODevice, it provides enhanced functionality.

CR/LF translation facilities are provided by applyCRLF() and removeCRLF(). These were broken first time I wrote them and I find it surprising how difficult it actually is to implement this 100% correctly. They are public as GUI code will want to apply CR/LF before exporting text to the clipboard and remove it when importing. The same functions can also perform Unicode conversions.

Data destruction is performed by shredData(). This uses an algorithm which thoroughly shreds the specified region, ensuring that the data cannot be recovered by any known process. The algorithm used involves XORing the existing data with pseudo-random data seeded with data from FX::Secure::Randomness, then writing zeros over the lot. All TnFOX file i/o devices call this on truncated data when IO_ShredTruncate is specified in the mode. If you wish to destroy an existing file, open it with IO_ShredTruncate, call truncate(0) and close before deleting.

QIODevice is extremely straightforward, so I won't bother explaining any more. What I will say is that there are two types of i/o device in TnFOX: (a) file and (b) synchronous. File i/o devices (eg; FX::FXFile, FX::QBuffer, FX::QMemMap, FX::QGZipDevice etc) let you perform reads and writes on a patch of data and thus they are interchangeable. Synchronous i/o devices (eg; FX::QPipe, FX::QBlkSocket, FX::QLocalPipe etc) which inherit off FX::QIODeviceS imply the use of two threads to use them because data reads in all of them wait for data to be written by the other side. Things like at() have no meaning and size() returns how much data is waiting to be read. Synchronous i/o devices are the foundation stone of Inter Process Communication (IPC) and are used mostly with FX::FXIPCMsg.

All i/o devices in TnFOX are thread-safe and can be used by multiple threads simultaneously though obviously there is only one current file pointer. You will have to synchronise that on your own. Furthermore, full access to the host security mechanism is provided by all i/o devices via permissions().

Differences from QIODevice

See also:
FX::QBuffer, FX::FXFile, FX::QBlkSocket, FX::QPipe, FX::QMemMap

Public Types

enum  CRLFType { Default, Unix, MacOS, MSDOS }
enum  UnicodeType {
  NoTranslation, UTF8, UTF16, UTF16LE,
  UTF32, UTF32LE
}
typedef FXfval Offset

Public Member Functions

FXuint flags () const
FXuint mode () const
FXuint state () const
CRLFType crlfFormat () const
void setCRLFFormat (CRLFType type)
UnicodeType unicodeTranslation () const
void setUnicodeTranslation (UnicodeType type)
bool isBuffered () const
bool isRaw () const
bool isTranslated () const
bool isUTF16Translated () const
bool isUTF32Translated () const
bool isReadable () const
bool isWriteable () const
bool isWritable () const
bool isReadWrite () const
bool isClosed () const
bool isInactive () const
bool isOpen () const
virtual bool isSynchronous () const
virtual bool open (FXuint mode)=0
virtual void close ()=0
virtual void flush ()=0
virtual FXfval size () const =0
virtual void truncate (FXfval size)=0
virtual FXfval at () const
virtual bool at (FXfval newpos)
virtual bool atEnd () const
virtual const FXACLpermissions () const
virtual void setPermissions (const FXACL &)
virtual FXuval readBlock (char *data, FXuval maxlen)=0
FXuval readBlock (FXuchar *data, FXuval maxlen)
virtual FXuval writeBlock (const char *data, FXuval maxlen)=0
FXuval writeBlock (const FXuchar *data, FXuval maxlen)
virtual FXuval readLine (char *data, FXuval maxlen)
virtual FXuval readBlockFrom (char *data, FXuval maxlen, FXfval pos)=0
FXuval readBlockFrom (FXuchar *data, FXuval maxlen, FXfval pos)
virtual FXuval writeBlockTo (FXfval pos, const char *data, FXuval maxlen)=0
FXuval writeBlockTo (FXfval pos, const FXuchar *data, FXuval maxlen)
virtual int getch ()
virtual int putch (int c)
virtual int ungetch (int c)=0
FXfval shredData (FXfval offset, FXfval len=(FXfval)-1)

Static Public Member Functions

static UnicodeType determineUnicodeType (FXuchar *data, FXuval len) throw ()
static FXuval applyCRLF (FXuchar *FXRESTRICT output, const FXuchar *FXRESTRICT input, FXuval outputlen, FXuval &inputlen, CRLFType crlftype=Default, UnicodeType utftype=NoTranslation)
static FXuval removeCRLF (FXuchar *FXRESTRICT output, const FXuchar *FXRESTRICT input, FXuval outputlen, FXuval &inputlen, UnicodeType utftype=NoTranslation)

Protected Member Functions

 QIODevice (const QIODevice &o)
QIODeviceoperator= (const QIODevice &o)
void setFlags (int f)
void setMode (int m)
void setState (int s)

Protected Attributes

FXfval ioIndex

Friends

FXAPI FXStreamoperator<< (FXStream &s, QIODevice &i)
FXAPI FXStreamoperator>> (FXStream &s, QIODevice &i)

Member Enumeration Documentation

The type of CR/LF encoding you want.

Enumerator:
Default  Uses the host OS format.
Unix  Uses ASCII 10 to delimit lines.
MacOS  Uses ASCII 13 to delimit lines.
MSDOS  Uses ASCII 13,10 to delimit lines.

The type of unicode translation you want.

Enumerator:
NoTranslation  Performs no translation.
UTF8  Outputs in native UTF-8.
UTF16  Converts between native (UTF-8) and UTF-16 big endian.
UTF16LE  Converts between native (UTF-8) and UTF-16 little endian.
UTF32  Converts between native (UTF-8) and UTF-32 big endian.
UTF32LE  Converts between native (UTF-8) and UTF-32 little endian.


Member Function Documentation

FXuint FX::QIODevice::flags (  )  const [inline]

Returns the flags of this device.

FXuint FX::QIODevice::mode (  )  const [inline]

Returns the mode of this device

See also:
QIODeviceOpenFlags

FXuint FX::QIODevice::state (  )  const [inline]

Returns the state of this device

See also:
QIODeviceStateFlags

CRLFType FX::QIODevice::crlfFormat (  )  const [inline]

Returns the CR/LF format of this device.

void FX::QIODevice::setCRLFFormat ( CRLFType  type  )  [inline]

Sets the CR/LF format for output of this device.

UnicodeType FX::QIODevice::unicodeTranslation (  )  const [inline]

Returns the unicode translation of this device.

void FX::QIODevice::setUnicodeTranslation ( UnicodeType  type  )  [inline]

Sets the unicode translation of this device.

bool FX::QIODevice::isBuffered (  )  const [inline]

Returns true if the device is buffered.

bool FX::QIODevice::isRaw (  )  const [inline]

Returns true if the device is unbuffered.

bool FX::QIODevice::isTranslated (  )  const [inline]

Returns true if the device is LR/CF translated.

bool FX::QIODevice::isUTF16Translated (  )  const [inline]

Returns true if the device is UTF-16 translated.

bool FX::QIODevice::isUTF32Translated (  )  const [inline]

Returns true if the device is UTF-32 translated.

bool FX::QIODevice::isReadable (  )  const [inline]

Returns true if the device is readable.

bool FX::QIODevice::isWriteable (  )  const [inline]

Returns true if the device is writeable.

bool FX::QIODevice::isReadWrite (  )  const [inline]

Returns true if the device is readable & writeable.

bool FX::QIODevice::isClosed (  )  const [inline]

Returns true if the device is closed.

bool FX::QIODevice::isOpen (  )  const [inline]

Returns true if the device is opened.

virtual bool FX::QIODevice::isSynchronous (  )  const [inline, virtual]

Returns true if this device is a synchronous device.

Reimplemented in FX::QIODeviceS, and FX::QSSLDevice.

virtual bool FX::QIODevice::open ( FXuint  mode  )  [pure virtual]

virtual void FX::QIODevice::close (  )  [pure virtual]

virtual void FX::QIODevice::flush (  )  [pure virtual]

virtual FXfval FX::QIODevice::size (  )  const [pure virtual]

Returns the size of the data being accessed by the device.

Implemented in FX::QBlkSocket, FX::QBuffer, FX::QBZip2Device, FX::QChildProcess, FX::QFile, FX::QGZipDevice, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual void FX::QIODevice::truncate ( FXfval  size  )  [pure virtual]

Truncates the data to the specified size. Extends the file if necessary & doesn't affect the current file pointer unless it is beyond the new file size, in which case it is moved to the end of the new file

Implemented in FX::QBuffer, FX::QBZip2Device, FX::QFile, FX::QGZipDevice, FX::QIODeviceS, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual FXfval FX::QIODevice::at (  )  const [virtual]

Returns the current file pointer within the device

Note:
With IO_Translate enabled, this increments faster than the return values from either readBlock() or writeBlock()

Reimplemented in FX::QBZip2Device, FX::QFile, FX::QGZipDevice, FX::QIODeviceS, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual bool FX::QIODevice::at ( FXfval  newpos  )  [virtual]

Sets the current file pointer

Note:
With IO_Translate enabled, setting to anything other than a previously read at() can be hazardous.

Reimplemented in FX::QBZip2Device, FX::QFile, FX::QGZipDevice, FX::QIODeviceS, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual bool FX::QIODevice::atEnd (  )  const [virtual]

Returns true if there is no more data available to be read from the device.

Reimplemented in FX::QBZip2Device, FX::QFile, FX::QGZipDevice, FX::QIODeviceS, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual const FXACL& FX::QIODevice::permissions (  )  const [virtual]

Returns the ACL for this device.

Reimplemented in FX::QBlkSocket, FX::QFile, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual void FX::QIODevice::setPermissions ( const FXACL  )  [virtual]

Sets the ACL for this device.

Reimplemented in FX::QFile, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual FXuval FX::QIODevice::readBlock ( char *  data,
FXuval  maxlen 
) [pure virtual]

Reads up to the specified quantity of bytes into the buffer, returning how much was actually read

Note:
With IO_Translate enabled, this routine regularly returns less read than maxlen (as the CR's are stripped out).

Implemented in FX::QBlkSocket, FX::QBuffer, FX::QBZip2Device, FX::QChildProcess, FX::QFile, FX::QGZipDevice, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual FXuval FX::QIODevice::writeBlock ( const char *  data,
FXuval  maxlen 
) [pure virtual]

Writes up to the specified quantity of bytes from the buffer, returning how much was actually written. Note that less being written due to error is returned as an exception, but some devices may write less in a non-error situation.

Implemented in FX::QBlkSocket, FX::QBuffer, FX::QBZip2Device, FX::QChildProcess, FX::QFile, FX::QGZipDevice, FX::QLocalPipe, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual FXuval FX::QIODevice::readLine ( char *  data,
FXuval  maxlen 
) [virtual]

Reads data until an end-of-line or maxlen is exceeded.

virtual FXuval FX::QIODevice::readBlockFrom ( char *  data,
FXuval  maxlen,
FXfval  pos 
) [pure virtual]

Combines an at() and readBlock() together. Can be much more efficient than those two operations individually with some i/o devices, plus it's synchronous and thus threadsafe

Implemented in FX::QBuffer, FX::QBZip2Device, FX::QFile, FX::QGZipDevice, FX::QIODeviceS, FX::QMemMap, and FX::QSSLDevice.

virtual FXuval FX::QIODevice::writeBlockTo ( FXfval  pos,
const char *  data,
FXuval  maxlen 
) [pure virtual]

Combines an at() and writeBlock() together. Can be much more efficient than those two operations individually with some i/o devices, plus it's synchronous and thus threadsafe

Implemented in FX::QBuffer, FX::QBZip2Device, FX::QFile, FX::QGZipDevice, FX::QIODeviceS, FX::QMemMap, and FX::QSSLDevice.

virtual int FX::QIODevice::getch (  )  [virtual]

Reads a single byte. Returns -1 for no data found.

Reimplemented in FX::QBuffer, FX::QBZip2Device, FX::QGZipDevice, and FX::QMemMap.

virtual int FX::QIODevice::putch ( int  c  )  [virtual]

Writes a single byte.

Reimplemented in FX::QBuffer, FX::QBZip2Device, FX::QGZipDevice, and FX::QMemMap.

virtual int FX::QIODevice::ungetch ( int  c  )  [pure virtual]

static UnicodeType FX::QIODevice::determineUnicodeType ( FXuchar *  data,
FXuval  len 
) throw () [static]

Looks at a sample of data and determines what kind of Unicode text it is, returning UnicodeType::NoTranslation if it isn't text. This routine isn't foolproof, but it's a good guess

static FXuval FX::QIODevice::applyCRLF ( FXuchar *FXRESTRICT  output,
const FXuchar *FXRESTRICT  input,
FXuval  outputlen,
FXuval &  inputlen,
CRLFType  crlftype = Default,
UnicodeType  utftype = NoTranslation 
) [static]

Applies CR/LF and optional UTF-x translation returning bytes output. If outputlen would run out before inputlen can be exhausted it will return early (eg; if mid newline, or mid UTF-x sequence). You should rewind processing to the difference between entrant inputlen and returned inputlen.

static FXuval FX::QIODevice::removeCRLF ( FXuchar *FXRESTRICT  output,
const FXuchar *FXRESTRICT  input,
FXuval  outputlen,
FXuval &  inputlen,
UnicodeType  utftype = NoTranslation 
) [static]

Removes CR/LF translation intelligently (ie; self-adjusts to MS-DOS, Unix and MacOS formats or any mixture of these) and can perform optional UTF-x translation, returning bytes output. If outputlen would run out before inputlen can be exhausted it will return early (eg; if mid newline, or mid UTF-x sequence). You should rewind processing to the difference between entrant inputlen and returned inputlen.

FXfval FX::QIODevice::shredData ( FXfval  offset,
FXfval  len = (FXfval)-1 
)

Destroys the len bytes of data from offset offset into the file. Restores the file pointer afterwards and returns how much data was shredded before end of file if encountered. You must have the device open for both reading and writing for this call to succeed.

void FX::QIODevice::setFlags ( int  f  )  [inline, protected]

Sets the flags.

void FX::QIODevice::setMode ( int  m  )  [inline, protected]

Sets the mode.

void FX::QIODevice::setState ( int  s  )  [inline, protected]

Sets the state.


Friends And Related Function Documentation

FXAPI FXStream& operator<< ( FXStream s,
QIODevice i 
) [friend]

Appends the contents of an i/o device to stream s

Warning:
This operation is not thread-safe

FXAPI FXStream& operator>> ( FXStream s,
QIODevice i 
) [friend]

Reads all available contents of the stream s to an i/o device, replacing its current contents and resetting the file pointer to the start

Warning:
This operation is not thread-safe


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

(C) 2002-2008 Niall Douglas. Some parts (C) to assorted authors.
Generated on Fri Jun 13 22:28:02 2008 for TnFOX by doxygen v1.5.6