qdatastream.3qt

Trolltech公司发布的基于C++图形开发环境

'\" t
.TH QDataStream 3qt "24 January 2005" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QDataStream \- Serialization of binary data to a
.br
.PP
\fC#include <qdatastream.h>\fR
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQDataStream\fR () "
.br
.ti -1c
.BI "\fBQDataStream\fR ( QIODevice * ) "
.br
.ti -1c
.BI "\fBQDataStream\fR ( QByteArray, int mode ) "
.br
.ti -1c
.BI "virtual \fB~QDataStream\fR () "
.br
.ti -1c
.BI "QIODevice* \fBdevice\fR () const"
.br
.ti -1c
.BI "void \fBsetDevice\fR ( QIODevice * ) "
.br
.ti -1c
.BI "void \fBunsetDevice\fR () "
.br
.ti -1c
.BI "bool \fBatEnd\fR () const"
.br
.ti -1c
.BI "bool eof () const \fI(obsolete)\fR"
.br
.ti -1c
.BI "enum \fBByteOrder\fR { BigEndian, LittleEndian }"
.br
.ti -1c
.BI "int \fBbyteOrder\fR () const"
.br
.ti -1c
.BI "void \fBsetByteOrder\fR ( int ) "
.br
.ti -1c
.BI "bool \fBisPrintableData\fR () const"
.br
.ti -1c
.BI "void \fBsetPrintableData\fR ( bool ) "
.br
.ti -1c
.BI "int \fBversion\fR () const"
.br
.ti -1c
.BI "void \fBsetVersion\fR ( int ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_INT8 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_UINT8 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_INT16 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_UINT16 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_INT32 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_UINT32 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_INT64 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( Q_UINT64 & i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( float & f ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( double & f ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator>>\fR ( char *& str ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_INT8 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_UINT8 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_INT16 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_UINT16 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_INT32 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_UINT32 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_INT64 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( Q_UINT64 i ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( float f ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( double f ) "
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR ( const char * str ) "
.br
.ti -1c
.BI "QDataStream& \fBreadBytes\fR ( char *&, uint & len ) "
.br
.ti -1c
.BI "QDataStream& \fBreadRawBytes\fR ( char *, uint len ) "
.br
.ti -1c
.BI "QDataStream& \fBwriteBytes\fR ( const char *, uint len ) "
.br
.ti -1c
.BI "QDataStream& \fBwriteRawBytes\fR ( const char *, uint len ) "
.br
.in -1c
.SH DESCRIPTION
The QDataStream class provides serialization of binary data to a QIODevice.
.PP
A data stream is a binary stream of encoded information which is 100% independent of the host computer operation system, CPU or byte order. A stream that is written by a PC under DOS/Windows can be read by a Sun SPARC running Solaris.
.PP
The QDataStream class implements serialization of primitive types, like \fCchar, short, int, char*\fR etc. Serialization of more complex data is accomplished by breaking up the data into primitive units.
.PP
The programmer 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.
.PP
A data stream cooperates closely with a QIODevice. A QIODevice represents an input/output medium one can read data from and write data to. The QFile class is an example of an IO device.
.PP
Example (write data to a stream):
.PP
.nf
.br
    QFile f( "file.dta" );
.br
    f.open( IO_WriteOnly );                     // open file for writing
.br
    QDataStream s( &f );                        // serialize using f
.br
    s << "the answer is";                       // serialize string
.br
    s << (Q_INT32)42;                           // serialize integer
.fi
.PP
Example (read data from a stream):
.PP
.nf
.br
    QFile f( "file.dta" );
.br
    f.open( IO_ReadOnly );                      // open file for reading
.br
    QDataStream s( &f );                        // serialize using f
.br
    char   *str;
.br
    Q_INT32 a;
.br
    s >> str >> a;                              // "the answer is" and 42
.br
    delete str;                                 // delete string
.fi
.PP
In the last example, if you read into a QString instead of a \fCchar*\fR you do not have to delete it.
.PP
Normally, each item written to the stream is written in a fixed binary format. For example, a \fCchar*\fR is written as a 32-bit integer equal to the length of the string including the NUL byte, followed by all the characters of the string including the NUL byte. Similarly when reading a string, 4 bytes are read to create the 32-bit length value, then that many characters for the string including the NUL. For a complete description of all Qt types supporting data streaming see Format of the QDataStream operators .
.PP
If you want a "parsing" input stream, see QTextStream. If you just want the data to be human-readable to aid in debugging, you can set the data stream into printable data mode with setPrintableData(). The data is then written slower, in a human readable bloated form that is sufficient for debugging.
.PP
If you are producing a new binary data format, such as a file format for documents created by your application, you could use a QDataStream 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:
.PP
.nf
.br
    // Open the file.
.br
    QFile f( "file.xxx" );
.br
    f.open( IO_WriteOnly );
.br
    QDataStream s( &f );
.br
.br
    // Write a header with a "magic number" and a version
.br
    s << 0xa0b0c0d0;
.br
    s << 123;
.br
.br
    // Write the data
.br
    s << [lots of interesting data]
.fi
.PP
Then read it in with:
.PP
.nf
.br
    // Open the file.
.br
    QFile f( "file.xxx" );
.br
    f.open( IO_ReadOnly );
.br
    QDataStream s( &f );
.br
.br