FX::FXStream Class Reference

#include <FXStream.h>

Inheritance diagram for FX::FXStream:

Inheritance graph
[legend]

List of all members.


Detailed Description

File format helper (Qt compatible).

FXStream is a modified version of FOX's FXStream - it is mostly API compatible but admittedly reflects the biggest divergence of API between FOX and TnFOX at the time of writing. Both share the purpose of serialising and deserialising data to and from a stored format and indeed via loadObject() and saveObject() can transfer entire window trees to and from storage.

Most use is simple - set which QIODevice it should use, and then use the << and >> operators to store and load respectively. position() lets you set or read the current offset into the file. Most classes in TnFOX (as well as FOX) provide overloads for these operators, so your << and >> overloads merely need to call << and >> on each of your data members you wish to save. Use load() and save() for blocks of individual units for efficiency.

Previous to FOX v1.1.31, FOX used FXStream mostly for dumping application state and its FXStream was not designed for general purpose file i/o. TnFOX uses FXStream for IPC which can traverse networks and CPU types, so it needs FXStream to be fast and always generate data in a universally understood format. You can of course use swapBytes() based on a flag within your data structure to avoid unnecessary endian conversions (and indeed this is what TnFOX's IPC classes do based on endian types on each end of the communications channel).

Since FOX v1.1.31, FXStream incorporates buffering and more general purpose facilities. The buffering in particular is left out because that's for the i/o device classes to implement if they want to. More importantly, IPC just would not work if a write to a pipe was coalesced into a larger packet sent sometime later.

Difference from FOX's FXStream & Qt's QDataStream

Endian translation is performed for you on big endian machines by default (simply because numerically more computers in the world are little endian, therefore we want to cost the least performance for the most people). Normal FOX always saves in native format and converts on load - and Qt is big endian by default.

Lastly, QDataStream's printable data format is unsupported. You don't need it with a decent debugger anyway (and it's ridiculously slow).

Useful tip:

Look into QBuffer's ability to dump itself onto a stream. This lets you very conveniently prepare parts of an overall image into separate sections. I've personally found that if you keep your end file image in a set of ordered nested QPtrList's & QBuffer's, writing it out is as simple as:

FXStream s;
QValueList<QPtrListOrBufferHolder> filedata;
s << filedata;
QValueList invokes the << operator on each of its members and so it recurses down calling each in turn. All QTL thunks provided in TnFOX provide default stream operators which require a null constructor in the type to compile.

Public Types

enum  ByteOrder { BigEndian, LittleEndian }

Public Member Functions

 FXStream (QIODevice *dev=0, const FXObject *cont=NULL)
QIODevicedevice () const
void setDevice (QIODevice *dev)
FXDEPRECATEDEXT void unsetDevice ()
bool atEnd () const
int byteOrder () const
void setByteOrder (int b)
FXDEPRECATEDEXT FXStreamreadBytes (char *&s, FXuint &l)
FXStreamreadRawBytes (char *buffer, FXuval len)
FXStreamreadRawBytes (FXuchar *buffer, FXuval len)
FXDEPRECATEDEXT FXStreamwriteBytes (const char *s, FXuint l)
FXStreamwriteRawBytes (const char *buffer, FXuval len)
FXStreamwriteRawBytes (const FXuchar *buffer, FXuval len)
FXfval rewind (FXint amount)
FXDEPRECATEDEXT FXStream (const FXObject *cont)
FXDEPRECATEDEXT bool open (FXStreamDirection save_or_load, FXuval size=8192, FXuchar *data=NULL)
virtual FXDEPRECATEDEXT bool flush ()
virtual bool close ()
FXDEPRECATEDEXT FXuval getSpace () const
FXDEPRECATEDEXT void setSpace (FXuval sp)
FXDEPRECATEDEXT FXStreamStatus status () const
bool eof () const
FXDEPRECATEDEXT void setError (FXStreamStatus err)
FXDEPRECATEDEXT FXStreamDirection direction () const
FXDEPRECATEDEXT const FXObjectcontainer () const
FXlong position () const
virtual bool position (FXlong offset, FXWhence whence=FXFromStart)
void swapBytes (FXint s)
bool swapBytes () const
void setBigEndian (bool big)
bool isBigEndian () const
FXStreamsave (const FXuchar *p, unsigned long n)
FXStreamsave (const FXchar *p, unsigned long n)
FXStreamsave (const FXushort *p, unsigned long n)
FXStreamsave (const FXshort *p, unsigned long n)
FXStreamsave (const FXuint *p, unsigned long n)
FXStreamsave (const FXint *p, unsigned long n)
FXStreamsave (const FXfloat *p, unsigned long n)
FXStreamsave (const FXdouble *p, unsigned long n)
FXStreamsave (const FXlong *p, unsigned long n)
FXStreamsave (const FXulong *p, unsigned long n)
FXStreamload (FXuchar *p, unsigned long n)
FXStreamload (FXchar *p, unsigned long n)
FXStreamload (FXushort *p, unsigned long n)
FXStreamload (FXshort *p, unsigned long n)
FXStreamload (FXuint *p, unsigned long n)
FXStreamload (FXint *p, unsigned long n)
FXStreamload (FXfloat *p, unsigned long n)
FXStreamload (FXdouble *p, unsigned long n)
FXStreamload (FXlong *p, unsigned long n)
FXStreamload (FXulong *p, unsigned long n)
FXStreamsaveObject (const FXObject *v)
FXStreamloadObject (FXObject *&v)
FXStreamaddObject (const FXObject *v)
virtual ~FXStream ()

Protected Member Functions

virtual FXuval writeBuffer (FXuval count)
virtual FXuval readBuffer (FXuval count)

Protected Attributes

FXHashhash
const FXObjectparent
FXuchar * begptr
FXuchar * endptr
FXuchar * wrptr
FXuchar * rdptr
FXlong pos
FXStreamDirection dir
FXStreamStatus code
FXuint seq
bool owns
bool swap
QIODevicedev

Friends

struct Generic::hasSerialise
struct Generic::hasDeserialise
FXStreamoperator<< (FXStream &s, const FXuchar &v)
FXStreamoperator<< (FXStream &s, const FXchar &v)
FXStreamoperator<< (FXStream &s, const FXushort &_v)
FXStreamoperator<< (FXStream &s, const FXshort &v)
FXStreamoperator<< (FXStream &s, const FXuint &_v)
FXStreamoperator<< (FXStream &s, const FXint &v)
FXStreamoperator<< (FXStream &s, const FXfloat &_v)
FXStreamoperator<< (FXStream &s, const FXdouble &_v)
FXStreamoperator<< (FXStream &s, const FXlong &v)
FXStreamoperator<< (FXStream &s, const FXulong &_v)
FXStreamoperator<< (FXStream &s, const char *v)
FXStreamoperator<< (FXStream &s, const bool &_v)
FXStreamoperator>> (FXStream &s, FXuchar &v)
FXStreamoperator>> (FXStream &s, FXchar &v)
FXStreamoperator>> (FXStream &s, FXushort &v)
FXStreamoperator>> (FXStream &s, FXshort &v)
FXStreamoperator>> (FXStream &s, FXuint &v)
FXStreamoperator>> (FXStream &s, FXint &v)
FXStreamoperator>> (FXStream &s, FXfloat &v)
FXStreamoperator>> (FXStream &s, FXdouble &v)
FXStreamoperator>> (FXStream &s, FXlong &v)
FXStreamoperator>> (FXStream &s, FXulong &v)
FXStreamoperator>> (FXStream &s, bool &v)

Constructor & Destructor Documentation

FX::FXStream::FXStream ( QIODevice dev = 0,
const FXObject cont = NULL 
)

Constructs an instance using device dev. cont is for FOX FXStream emulation only.

FXDEPRECATEDEXT FX::FXStream::FXStream ( const FXObject cont  ) 

Deprecated:
For FOX compatibility only
Construct stream with given container object. The container object is an object that will itself not be saved to or loaded from the stream, but which may be referenced by other objects. These references will be properly saved and restored.

virtual FX::FXStream::~FXStream (  )  [virtual]

Destructor.


Member Function Documentation

QIODevice* FX::FXStream::device (  )  const [inline]

Returns the i/o device this stream is using.

void FX::FXStream::setDevice ( QIODevice dev  ) 

Sets the i/o device this stream is using.

FXDEPRECATEDEXT void FX::FXStream::unsetDevice (  )  [inline]

Deprecated:
For Qt compatibility only

bool FX::FXStream::atEnd (  )  const [inline]

Returns true if there is no more data to be read.

int FX::FXStream::byteOrder (  )  const [inline]

Returns the byte order the data on the i/o device shall be interpreted in.

void FX::FXStream::setByteOrder ( int  b  )  [inline]

Sets the byte order the data on the i/o device shall be interpreted in.

FXDEPRECATEDEXT FXStream& FX::FXStream::readBytes ( char *&  s,
FXuint &  l 
)

Deprecated:
For Qt compatibility only

FXStream& FX::FXStream::readRawBytes ( char *  buffer,
FXuval  len 
) [inline]

Reads preformatted byte data into the specified buffer.

FXDEPRECATEDEXT FXStream& FX::FXStream::writeBytes ( const char *  s,
FXuint  l 
)

Deprecated:
For Qt compatibility only

FXStream& FX::FXStream::writeRawBytes ( const char *  buffer,
FXuval  len 
) [inline]

Writes preformatted byte data from the specified buffer.

FXfval FX::FXStream::rewind ( FXint  amount  ) 

Moves the file pointer backwards by the specified amount of bytes, returning the new file pointer.

virtual FXuval FX::FXStream::writeBuffer ( FXuval  count  )  [protected, virtual]

Write at least count bytes from the buffer; returns number of bytes available to be written.

virtual FXuval FX::FXStream::readBuffer ( FXuval  count  )  [protected, virtual]

Read at least count bytes into the buffer; returns number of bytes available to be read.

FXDEPRECATEDEXT bool FX::FXStream::open ( FXStreamDirection  save_or_load,
FXuval  size = 8192,
FXuchar *  data = NULL 
)

Deprecated:
For FOX compatibility only
Open stream for reading (FXStreamLoad) or for writing (FXStreamSave). An initial buffer size may be given, which must be at least 16 bytes. If data is not NULL, it is expected to point to an external data buffer of length size; otherwise stream will use an internally managed buffer.

Reimplemented in FX::FXMemoryStream.

virtual FXDEPRECATEDEXT bool FX::FXStream::flush (  )  [virtual]

Deprecated:
For FOX compatibility only
Flush buffer

Reimplemented in FX::FXBZFileStream, and FX::FXGZFileStream.

virtual bool FX::FXStream::close (  )  [virtual]

Deprecated:
For FOX compatibility only
Close; return true if OK

Reimplemented in FX::FXBZFileStream, FX::FXFileStream, FX::FXGZFileStream, and FX::FXMemoryStream.

FXDEPRECATEDEXT FXuval FX::FXStream::getSpace (  )  const

Deprecated:
For FOX compatibility only
Get available buffer space

FXDEPRECATEDEXT void FX::FXStream::setSpace ( FXuval  sp  ) 

Deprecated:
For FOX compatibility only
Set available buffer space

FXDEPRECATEDEXT FXStreamStatus FX::FXStream::status (  )  const [inline]

Deprecated:
For FOX compatibility only
Get status code

bool FX::FXStream::eof (  )  const [inline]

Return true if at end of file or error.

FXDEPRECATEDEXT void FX::FXStream::setError ( FXStreamStatus  err  ) 

Deprecated:
For FOX compatibility only
Set status code

FXDEPRECATEDEXT FXStreamDirection FX::FXStream::direction (  )  const [inline]

Deprecated:
For FOX compatibility only
Obtain stream direction

FXDEPRECATEDEXT const FXObject* FX::FXStream::container (  )  const [inline]

Deprecated:
For FOX compatibility only
Get parent object

FXlong FX::FXStream::position (  )  const

Get position.

virtual bool FX::FXStream::position ( FXlong  offset,
FXWhence  whence = FXFromStart 
) [virtual]

Move to position relative to head, tail, or current location.

void FX::FXStream::swapBytes ( FXint  s  )  [inline]

Change swap bytes flag. -1 sets machine default (ie; do swap on big endian machines).

bool FX::FXStream::swapBytes (  )  const [inline]

Get state of the swap bytes flag.

void FX::FXStream::setBigEndian ( bool  big  )  [inline]

Set stream to big endian mode if true. Byte swapping will be enabled if the machine native byte order is not equal to the desired byte order.

bool FX::FXStream::isBigEndian (  )  const [inline]

Return true if big endian mode.

FXStream& FX::FXStream::save ( const FXuchar *  p,
unsigned long  n 
) [inline]

Save arrays of items to stream.

FXStream& FX::FXStream::load ( FXuchar *  p,
unsigned long  n 
) [inline]

Load arrays of items from stream.

FXStream& FX::FXStream::saveObject ( const FXObject v  ) 

Save object.

FXStream& FX::FXStream::loadObject ( FXObject *&  v  ) 

Load object.

FXStream& FX::FXStream::addObject ( const FXObject v  ) 

Add object without saving or loading.


Friends And Related Function Documentation

FXStream& operator<< ( FXStream s,
const FXuchar &  v 
) [friend]

Save single items to stream.

FXStream& operator>> ( FXStream s,
FXuchar &  v 
) [friend]

Load single items from stream.


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:18:07 2008 for TnFOX by doxygen v1.5.6