From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqdatastream.html | 570 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 570 insertions(+) create mode 100644 doc/html/ntqdatastream.html (limited to 'doc/html/ntqdatastream.html') diff --git a/doc/html/ntqdatastream.html b/doc/html/ntqdatastream.html new file mode 100644 index 00000000..a20fd8ea --- /dev/null +++ b/doc/html/ntqdatastream.html @@ -0,0 +1,570 @@ + + + + + +TQDataStream Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQDataStream Class Reference

+ +

The TQDataStream class provides serialization of binary data +to a TQIODevice. +More... +

All the functions in this class are reentrant when TQt is built with thread support.

+

#include <ntqdatastream.h> +

List of all member functions. +

Public Members

+ +

Detailed Description

+ + + +The TQDataStream class provides serialization of binary data +to a TQIODevice. +

+

A data stream is a binary stream of encoded information which is +100% independent of the host computer's operating system, CPU or +byte order. For example, a data stream that is written by a PC +under Windows can be read by a Sun SPARC running Solaris. +

You can also use a data stream to read/write raw + unencoded binary data. If you want a "parsing" input +stream, see TQTextStream. +

The TQDataStream class implements the serialization of C++'s basic +data types, like char, short, int, char*, etc. +Serialization of more complex data is accomplished by breaking up +the data into primitive units. +

A data stream cooperates closely with a TQIODevice. A TQIODevice +represents an input/output medium one can read data from and write +data to. The TQFile class is an example of an IO device. +

Example (write binary data to a stream): +

+    TQFile file( "file.dat" );
+    file.open( IO_WriteOnly );
+    TQDataStream stream( &file ); // we will serialize the data into the file
+    stream << "the answer is";   // serialize a string
+    stream << (Q_INT32)42;       // serialize an integer
+
+ +

Example (read binary data from a stream): +

+    TQFile file( "file.dat" );
+    file.open( IO_ReadOnly );
+    TQDataStream stream( &file );  // read the data serialized from the file
+    TQString str;
+    Q_INT32 a;
+    stream >> str >> a;           // extract "the answer is" and 42
+
+ +

Each item written to the stream is written in a predefined binary +format that varies depending on the item's type. Supported TQt +types include TQBrush, TQColor, TQDateTime, TQFont, TQPixmap, TQString, +TQVariant and many others. For the complete list of all TQt types +supporting data streaming see the Format of the TQDataStream operators. +

For integers it is best to always cast to a TQt integer type for +writing, and to read back into the same TQt integer type. This +ensures that you get integers of the size you want and insulates +you from compiler and platform differences. +

To take one example, a char* string is written as a 32-bit +integer equal to the length of the string including the NUL byte +('\0'), followed by all the characters of the string including the +NUL byte. When reading a char* string, 4 bytes are read to +create the 32-bit length value, then that many characters for the +char* string including the NUL are read. +

The initial IODevice is usually set in the constructor, but can be +changed with setDevice(). If you've reached the end of the data +(or if there is no IODevice set) atEnd() will return TRUE. +

If you want the data to be compatible with an earlier version of +TQt use setVersion(). +

If you want the data to be human-readable, e.g. for debugging, you +can set the data stream into printable data mode with +setPrintableData(). The data is then written slower, in a bloated +but human readable format. +

If you are producing a new binary data format, such as a file +format for documents created by your application, you could use a +TQDataStream to write the data in a portable format. Typically, you +would write a brief header containing a magic string and a version +number to give yourself room for future expansion. For example: +

+    TQFile file( "file.xxx" );
+    file.open( IO_WriteOnly );
+    TQDataStream stream( &file );
+
+    // Write a header with a "magic number" and a version
+    stream << (Q_UINT32)0xA0B0C0D0;
+    stream << (Q_INT32)123;
+
+    // Write the data
+    stream << [lots of interesting data]
+
+ +

Then read it in with: +

+    TQFile file( "file.xxx" );
+    file.open( IO_ReadOnly );
+    TQDataStream stream( &file );
+
+    // Read and check the header
+    Q_UINT32 magic;
+    stream >> magic;
+    if ( magic != 0xA0B0C0D0 )
+        return XXX_BAD_FILE_FORMAT;
+
+    // Read the version
+    Q_INT32 version;
+    stream >> version;
+    if ( version < 100 )
+        return XXX_BAD_FILE_TOO_OLD;
+    if ( version > 123 )
+        return XXX_BAD_FILE_TOO_NEW;
+    if ( version <= 110 )
+        stream.setVersion(1);
+
+    // Read the data
+    stream >> [lots of interesting data];
+    if ( version > 120 )
+        stream >> [data new in XXX version 1.2];
+    stream >> [other interesting data];
+
+ +

You can select which byte order to use when serializing data. The +default setting is big endian (MSB first). Changing it to little +endian breaks the portability (unless the reader also changes to +little endian). We recommend keeping this setting unless you have +special requirements. +

+

Reading and writing raw binary data +

+

You may wish to read/write your own raw binary data to/from the +data stream directly. Data may be read from the stream into a +preallocated char* using readRawBytes(). Similarly data can be +written to the stream using writeRawBytes(). Notice that any +encoding/decoding of the data must be done by you. +

A similar pair of functions is readBytes() and writeBytes(). These +differ from their raw counterparts as follows: readBytes() +reads a Q_UINT32 which is taken to be the length of the data to be +read, then that number of bytes is read into the preallocated +char*; writeBytes() writes a Q_UINT32 containing the length of the +data, followed by the data. Notice that any encoding/decoding of +the data (apart from the length Q_UINT32) must be done by you. +

See also TQTextStream, TQVariant, and Input/Output and Networking. + +

Member Type Documentation

+

TQDataStream::ByteOrder

+ +

The byte order used for reading/writing the data. +

+

Member Function Documentation

+

TQDataStream::TQDataStream () +

+Constructs a data stream that has no IO device. +

See also setDevice(). + +

TQDataStream::TQDataStream ( TQIODevice * d ) +

+Constructs a data stream that uses the IO device d. +

Warning: If you use TQSocket or TQSocketDevice as the IO device d +for reading data, you must make sure that enough data is available +on the socket for the operation to successfully proceed; +TQDataStream does not have any means to handle or recover from +short-reads. +

See also setDevice() and device(). + +

TQDataStream::TQDataStream ( TQByteArray a, int mode ) +

+Constructs a data stream that operates on a byte array, a, +through an internal TQBuffer device. The mode is a +TQIODevice::mode(), usually either IO_ReadOnly or IO_WriteOnly. +

Example: +

+    static char bindata[] = { 231, 1, 44, ... };
+    TQByteArray a;
+    a.setRawData( bindata, sizeof(bindata) );   // a points to bindata
+    TQDataStream stream( a, IO_ReadOnly );       // open on a's data
+    stream >> [something];                      // read raw bindata
+    a.resetRawData( bindata, sizeof(bindata) ); // finished
+
+ +

The TQByteArray::setRawData() function is not for the inexperienced. + +

TQDataStream::~TQDataStream () [virtual] +

+Destroys the data stream. +

The destructor will not affect the current IO device, unless it is +an internal IO device processing a TQByteArray passed in the constructor, in which case the internal IO device is destroyed. + +

bool TQDataStream::atEnd () const +

+ +

Returns TRUE if the IO device has reached the end position (end of +the stream or file) or if there is no IO device set; otherwise +returns FALSE, i.e. if the current position of the IO device is +before the end position. +

See also TQIODevice::atEnd(). + +

int TQDataStream::byteOrder () const +

+ +

Returns the current byte order setting -- either BigEndian or +LittleEndian. +

See also setByteOrder(). + +

TQIODevice * TQDataStream::device () const +

+ +

Returns the IO device currently set. +

See also setDevice() and unsetDevice(). + +

bool TQDataStream::eof () const +

+

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Returns TRUE if the IO device has reached the end position (end of +stream or file) or if there is no IO device set. +

Returns FALSE if the current position of the read/write head of the IO +device is somewhere before the end position. +

See also TQIODevice::atEnd(). + +

bool TQDataStream::isPrintableData () const +

+ +

Returns TRUE if the printable data flag has been set; otherwise +returns FALSE. +

See also setPrintableData(). + +

TQDataStream & TQDataStream::operator<< ( Q_INT8 i ) +

+Writes a signed byte, i, to the stream and returns a reference +to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_UINT8 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes an unsigned byte, i, to the stream and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_INT16 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes a signed 16-bit integer, i, to the stream and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_UINT16 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes an unsigned 16-bit integer, i, to the stream and returns +a reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_INT32 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes a signed 32-bit integer, i, to the stream and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_UINT32 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes an unsigned integer, i, to the stream as a 32-bit +unsigned integer (Q_UINT32). Returns a reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_INT64 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes a signed 64-bit integer, i, to the stream and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_UINT64 i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes an unsigned 64-bit integer, i, to the stream and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_LONG i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes a signed integer i, of the system's word length, to the +stream and returns a reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( Q_ULONG i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes an unsigned integer i, of the system's word length, to +the stream and returns a reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( float f ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes a 32-bit floating point number, f, to the stream using +the standard IEEE754 format. Returns a reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( double f ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes a 64-bit floating point number, f, to the stream using +the standard IEEE754 format. Returns a reference to the stream. + +

TQDataStream & TQDataStream::operator<< ( const char * s ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes the '\0'-terminated string s to the stream and returns a +reference to the stream. +

The string is serialized using writeBytes(). + +

TQDataStream & TQDataStream::operator>> ( Q_INT8 & i ) +

+Reads a signed byte from the stream into i, and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_UINT8 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads an unsigned byte from the stream into i, and returns a +reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_INT16 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads a signed 16-bit integer from the stream into i, and +returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_UINT16 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads an unsigned 16-bit integer from the stream into i, and +returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_INT32 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads a signed 32-bit integer from the stream into i, and +returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_UINT32 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads an unsigned 32-bit integer from the stream into i, and +returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_INT64 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads a signed 64-bit integer from the stream into i, and +returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_UINT64 & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads an unsigned 64-bit integer from the stream, into i, and +returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( Q_LONG & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads a signed integer of the system's word length from the stream +into i, and returns a reference to the stream. +

+

TQDataStream & TQDataStream::operator>> ( Q_ULONG & i ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads an unsigned integer of the system's word length from the +stream, into i, and returns a reference to the stream. + +

TQDataStream & TQDataStream::operator>> ( float & f ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads a 32-bit floating point number from the stream into f, +using the standard IEEE754 format. Returns a reference to the +stream. + +

TQDataStream & TQDataStream::operator>> ( double & f ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads a 64-bit floating point number from the stream into f, +using the standard IEEE754 format. Returns a reference to the +stream. + +

TQDataStream & TQDataStream::operator>> ( char *& s ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Reads the '\0'-terminated string s from the stream and returns +a reference to the stream. +

Space for the string is allocated using new -- the caller must +destroy it with delete[]. + +

TQDataStream & TQDataStream::readBytes ( char *& s, uint & l ) +

+Reads the buffer s from the stream and returns a reference to +the stream. +

The buffer s is allocated using new. Destroy it with the delete[] operator. If the length is zero or s cannot be +allocated, s is set to 0. +

The l parameter will be set to the length of the buffer. +

The serialization format is a Q_UINT32 length specifier first, +then l bytes of data. Note that the data is not encoded. +

See also readRawBytes() and writeBytes(). + +

TQDataStream & TQDataStream::readRawBytes ( char * s, uint len ) +

+Reads len bytes from the stream into s and returns a +reference to the stream. +

The buffer s must be preallocated. The data is not encoded. +

See also readBytes(), TQIODevice::readBlock(), and writeRawBytes(). + +

void TQDataStream::setByteOrder ( int bo ) +

+Sets the serialization byte order to bo. +

The bo parameter can be TQDataStream::BigEndian or TQDataStream::LittleEndian. +

The default setting is big endian. We recommend leaving this +setting unless you have special requirements. +

See also byteOrder(). + +

void TQDataStream::setDevice ( TQIODevice * d ) +

+void TQDataStream::setDevice(TQIODevice *d ) +

Sets the IO device to d. +

See also device() and unsetDevice(). + +

void TQDataStream::setPrintableData ( bool enable ) +

+ +

If enable is TRUE, data will be output in a human readable +format. If enable is FALSE, data will be output in a binary +format. +

If enable is TRUE, the write functions will generate output +that consists of printable characters (7 bit ASCII). This output +will typically be a lot larger than the default binary output, and +consequently slower to write. +

We recommend only enabling printable data for debugging purposes. + +

void TQDataStream::setVersion ( int v ) +

+ +

Sets the version number of the data serialization format to v. +

You don't need to set a version if you are using the current +version of TQt. +

In order to accommodate new functionality, the datastream +serialization format of some TQt classes has changed in some +versions of TQt. If you want to read data that was created by an +earlier version of TQt, or write data that can be read by a program +that was compiled with an earlier version of TQt, use this function +to modify the serialization format of TQDataStream. +

+
TQt Version TQDataStream Version +
TQt 3.3 6 +
TQt 3.2 5 +
TQt 3.1 5 +
TQt 3.0 4 +
TQt 2.1.x and TQt 2.2.x 3 +
TQt 2.0.x 2 +
TQt 1.x 1 +
+

See also version(). + +

void TQDataStream::unsetDevice () +

+Unsets the IO device. This is the same as calling setDevice( 0 ). +

See also device() and setDevice(). + +

int TQDataStream::version () const +

+ +

Returns the version number of the data serialization format. In TQt +3.1, this number is 5. +

See also setVersion(). + +

TQDataStream & TQDataStream::writeBytes ( const char * s, uint len ) +

+Writes the length specifier len and the buffer s to the +stream and returns a reference to the stream. +

The len is serialized as a Q_UINT32, followed by len bytes +from s. Note that the data is not encoded. +

See also writeRawBytes() and readBytes(). + +

TQDataStream & TQDataStream::writeRawBytes ( const char * s, uint len ) +

+Writes len bytes from s to the stream and returns a +reference to the stream. The data is not encoded. +

See also writeBytes(), TQIODevice::writeBlock(), and readRawBytes(). + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1