[QT] QDataStream類參考

QDataStream類提供了位元據到QIODevice的序列化。

#include <qdatastream.h>

所
有成員函數的列表。

公有成員

• QDataStream
  ()
• QDataStream
  ( QIODevice * d )
• QDataStream
  ( QByteArray a, int mode )
• virtual ~QDataStream
  ()
• QIODevice * device
  () const
• void setDevice
  ( QIODevice * d )
• void unsetDevice
  ()
• bool atEnd
  () const
• bool eof () const  (obsolete)
• enum ByteOrder
  { BigEndian, LittleEndian }
• int byteOrder
  () const
• void setByteOrder
  ( int bo )
• bool isPrintableData
  () const
• void setPrintableData
  ( bool enable )
• int version
  () const
• void setVersion
  ( int v )
• QDataStream & operator>>
  ( Q_INT8 & i )
• QDataStream & operator>>
  ( Q_UINT8 & i )
• QDataStream & operator>>
  ( Q_INT16 & i )
• QDataStream & operator>>
  ( Q_UINT16 & i )
• QDataStream & operator>>
  ( Q_INT32 & i )
• QDataStream & operator>>
  ( Q_UINT32 & i )
• QDataStream & operator>>
  ( Q_LONG & i )
• QDataStream & operator>>
  ( Q_ULONG & i )
• QDataStream & operator>>
  ( float & f )
• QDataStream & operator>>
  ( double & f )
• QDataStream & operator>>
  ( char *& s )
• QDataStream & operator<<
  ( Q_INT8 i )
• QDataStream & operator<<
  ( Q_UINT8 i )
• QDataStream & operator<<
  ( Q_INT16 i )
• QDataStream & operator<<
  ( Q_UINT16 i )
• QDataStream & operator<<
  ( Q_INT32 i )
• QDataStream & operator<<
  ( Q_UINT32 i )
• QDataStream & operator<<
  ( Q_LONG i )
• QDataStream & operator<<
  ( Q_ULONG i )
• QDataStream & operator<<
  ( float f )
• QDataStream & operator<<
  ( double f )
• QDataStream & operator<<
  ( const char * s )
• QDataStream & readBytes
  ( char *& s, uint & l )
• QDataStream & readRawBytes
  ( char * s, uint len )
• QDataStream & writeBytes
  ( const char * s, uint len )
• QDataStream & writeRawBytes
  ( const char * s, uint len )

詳細描述

QDataStream類提供了位元據到QIODevice的序列化。

 

資料流是一個編碼資訊的二進位流，它與主機的作業系統、CPU或位元組順序100％的沒有關係。比如一個在PC的Windows下寫的資料流可以在Sun
SPARC的Solaris中讀出。

QTextStream.
你也可以使用一個資料流來讀/寫原始的未編碼的位元據。
如果你想“解析”輸入資料流，請參考QTextStream。

QDataStream類實現了基本類型的序列化，比如char
、short
、int
、char*
等
等。更加複雜的類型的序列化是通過把資料分解為簡單單元來實現的。

資料流和QIODevice合作非常緊密。QIODevice描述了一個可以從中讀資料和向它寫資料的輸入/輸出介質。QFile類就是一個IO裝置的例子。

執行個體（向一個流中寫位元據）：

    QFile f( "file.dta" );
    f.open( IO_WriteOnly );
    QDataStream s( &f );    // 我們將把資料序列化至檔案f
    s << "the answer is";   // 序列化一個字串
    s << (Q_INT32)42;       // 序列化一個整數

執行個體（從一個流中讀位元據）：

    QFile f( "file.dta" );
    f.open( IO_ReadOnly );
    QDataStream s( &f );    // 從檔案f中讀取序列化的資料
    QString str;
    Q_INT32 a;
    s >> str >> a;          // 提取出“the answer is”和42

每一個要寫到流中的項都被寫成一種預定義的二進位格式，這種格式取決於這個項的類型。Qt中支援的類型有QBrush、QColor、QDateTime、QFont、QPixmap、QString、QVariant和其它一些。支援數
據流的所有的Qt類型的列表請看QDataStream操作
符的格式。

舉個例子，char*
字串被寫做一個等於包括NUL位元組的字串長度的32位整數，後面跟著字串中包括NUL位元組
的所有位元組。當讀取char*
字串的時候，先讀4個位元組建立一個32位長度值，然後讀取包括NUL的這麼多的位元組到char*
字
符串中。

初始的IODevice通常在建構函式中設定，但是也可以使用setDevice()
來改變。如果你到達了資料的終點（或者如果沒有IODevice被設定），atEnd()將
返回真。

如果你希望資料和以前版本的Qt一致，請使用setVersion()。

如果你希望資料是人們可讀的，比如，用於調試，你可以用setPrintableData()
設定資料流為可列印資料模式。然後這個資料寫起來慢一些，並且膨脹起來但已經是人們可以讀取的格式了。

如果你正在產生一種新的位元據格式，比如是你的應用程式建立的一種文檔的檔案格式，你可以使用QDataStream來把資料寫成一種可移植的格式。
通常，你可以寫一個包含幻數字串和版本資訊的簡要的頭資訊，這樣可以給你以後的擴充提供一定的空間。比如：

 

    QFile f( "file.xxx" );
    f.open( IO_WriteOnly );
    QDataStream s( &f );

    // 寫一個含有“幻數”和版本號碼的頭
    s << (Q_UINT32)0xa0b0c0d0;
    s << (Q_INT32)123;

    // 寫資料
    s << [lots of interesting data]

然後這樣讀：

 

    QFile f( "file.xxx" );
    f.open( IO_ReadOnly );
    QDataStream s( &f );

    // 讀取並檢查頭
    Q_UINT32 magic;
    s >> magic;
    if ( magic != 0xa0b0c0d0 )
        return XXX_BAD_FILE_FORMAT;

    // 讀取版本號碼
    Q_INT32 version;
    s >> version;
    if ( version < 100 )
        return XXX_BAD_FILE_TOO_OLD;
    if ( version > 123 )
        return XXX_BAD_FILE_TOO_NEW;
    if ( version <= 110 )
        s.setVersion(1);

    // 讀取資料
    s >> [很多有趣的資料];
    if ( version > 120 )
        s >> [在1.2版中的新資料XXX];
    s >> [其它有趣的資料];

當你序列化資料的時候，你可以選擇你要使用的位元組順序。預設的設定是高位元組在前。把它改變為低位元組在前會破壞可移植性（除非讀取程式也是用低位元組在前）。
我們建議你使用預設設定，除非你有特殊需要。

讀寫原始位元據

你也許希望把你自己的原始位元據直接寫到資料流中，或者從資料流中直接讀取它們。資料可以使用
readRawBytes()
從流中讀取到一個預先分配好的char*。同樣地也可以使用writeRawBytes()
把資料寫到流中。注意，任何資料的編碼/解碼就只能由你自己來完成了。

一對相似的函數readBytes()
和writeBytes()。
它們與操作未經處理資料
的那兩個的區別是：readBytes()先讀取可讀的資料長度到一個Q_UINT32，然後讀取這個數量的位元組到
已經預先分配空間的char*；writeBytes()寫一個包含資料長度的Q_UNIT32，然後再是資料。注意任何資料的編碼/解碼（除了長度
Q_UINT32）都必須由你自己來做。

 

也可以參考QTextStream、QVariant和輸入/輸出和網路。

成員類型文檔
QDataStream::ByteOrder

讀/寫資料時使用的位元組順序。

• QDataStream::BigEndian
  - 高位在前（預設的）
• QDataStream::LittleEndian
  - 低位在前

成員函數文檔
QDataStream::QDataStream ()

構造一個沒有IO裝置的資料流。

 

也可以參考setDevice()。

QDataStream::QDataStream (
QIODevice * d
)

構造一個使用IO裝置d
的資料流。

警告：
如果你使用QSocket或QSocketDevice來
作為IO裝置d
進行讀資料，為了確保操作能夠成功地執行，你必須確認在通訊端提供了足夠的資料，QDataStream沒有任何方法來
處理和恢複這種讀取缺少地情況。

 

也可以參考setDevice()
and device().

QDataStream::QDataStream (
QByteArray a,
int mode )

構造一個通過內建的QBuffer設
備來操作一個位元組數組a
的資料流。mode
就是QIODevice::mode()，
通常不是IO_ReadOnly就
是IO_WriteOnly。

執行個體：

    static char bindata[] = { 231, 1, 44, ... };
    QByteArray a;
    a.setRawData( bindata, sizeof(bindata) );   // a指向bindata
    QDataStream s( a, IO_ReadOnly );            // 開啟a的資料
    s >> [something];                           // 讀取原始的bindata
    a.resetRawData( bindata, sizeof(bindata) ); // 完成

QByteArray::setRawData()
函數不是提供給沒有經驗的人的。

QDataStream::~QDataStream
() [虛]

銷毀這個資料流。

解構函式對當前的IO裝置沒有任何效果，除非他是一個通過建構函式
傳遞的一個處理QByteArray的內部IO
裝置，這種情況下，內部IO裝置被銷毀。。

bool
QDataStream::atEnd () const

如果IO裝置已經到達終點（流或檔案的終點），或者如果沒有IO裝置被設定，返回真，否則返回假，比如，如果IO裝置當前位置在終點之前。

 

也可以參考QIODevice::atEnd()。

int
QDataStream::byteOrder ()
const

返回當前位元組順序設定——不是BigEndian就
是LittleEndian

。

 

也可以參考setByteOrder()。

QIODevice *
QDataStream::device () const

返回當前設定的IO裝置。

也可以參考setDevice()
和unsetDevice()。

bool
QDataStream::eof () const

這個函數是廢棄的。
它的提供只是為了保證舊代碼能夠工作。我們強烈建議在新代碼中不要使用它。

如果IO裝置到達終點（流或檔案的終點），或者如果沒有IO裝置被設定，返回真。

如果當前的IO的讀寫位置在終點之前，返回假。

 

也可以參考QIODevice::atEnd()。

bool
QDataStream::isPrintableData
() const

如果可列印資料標記已經被設定，返回真。

也可以參考setPrintableData()。

QDataStream &

QDataStream::operator<< ( Q_INT8 i )

寫一個有符號的位元組i

到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
Q_UINT8 i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個無符號的位元組i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
Q_INT16 i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個有符號的16位整數i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
Q_UINT16 i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個無符號的16位整數i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
Q_INT32 i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個有符號的32位整數i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
Q_UINT32 i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個無符號的32位整數i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< ( Q_LONG i
)

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個有符號的，長度為系統字長度的整數i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
Q_ULONG i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個無符號的，長度為系統字長度的整數i
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< ( float f )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個使用標準IEEE754格式的32位浮點數f
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< ( double f
)

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個使用標準IEEE754格式的64位浮點數f
到流中並返迴流的引用。

QDataStream &

QDataStream::operator<< (
const char * s )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

寫一個以“/0”結尾的字串s
到流中並返迴流的引用。

這個字串是使用writeBytes()
序列化的。

QDataStream &

QDataStream::operator>> (
Q_INT8 & i )

從流中讀取一個有符號的位元組到i

並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_UINT8 & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個無符號的位元組到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_INT16 & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個有符號的16位整數到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_UINT16 & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個無符號的16位整數到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_INT32 & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個有符號的32位整數到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_UINT32 & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個無符號的32位整數到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_LONG & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個有符號的，長度為系統字長度的整數到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
Q_ULONG & i )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個無符號的，長度為系統字長度的整數到i
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
float & f )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個使用標準IEEE754格式的32位浮點數到f
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
double & f )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個使用標準IEEE754格式的64位浮點數到f
並返迴流的引用。

QDataStream &

QDataStream::operator>> (
char *& s )

這是一個重載成員函數，提供了方便。它的行為基本上和上面的函數相同。

從流中讀取一個以“/0”結尾的字串到s
並返迴流的引用。

存放這個字串的空間是使用new
來分配的——調用者必須使用delete[]
來銷毀它。

QDataStream &

QDataStream::readBytes ( char *& s,
uint & l )

從流中讀取緩衝s
並返迴流的引用。

這個緩衝s
是使用new
來分配的。需要使用delete[]
來銷毀它。如果長度為0或者s
沒
能被分配，s
就被設定為0。

l
參數將被設定為緩衝的長度。

序列化格式首先是一個Q_UINT32長度的說明符，然後是l
位元組的資料。注意資料不是
編碼的。

 

也可以參考readRawBytes()
和writeBytes()。

QDataStream &

QDataStream::readRawBytes ( char * s,
uint len )

從流中讀取len
位元組到s
並返迴流的引用。

這個緩衝s
必須被預先分配。資料不是
編碼的。

 

也可以參考readBytes()、QIODevice::readBlock()
和writeRawBytes()。

void
QDataStream::setByteOrder
( int bo )

設定序列化位元組順序為bo
。

bo
參數可以是QDataStream::BigEndian或QDataStream::LittleEndian。

預設設定是高位元組在前。我們強烈建議你保留這個設定，除非你有特殊需要。

 

也可以參考byteOrder()。

void
QDataStream::setDevice (
QIODevice * d
)

設定IO裝置為d

。

也可以參考device()
和unsetDevice()。

void
QDataStream::setPrintableData
( bool enable )

設定（如果enable
為真）或者清空可列印資料標記。

如果這個標記被設定，寫函數將產生由可列印字元（7位ASCII碼）的輸出。

我們建議只有在調試的情況下開啟可列印資料設定（它比較慢並且產生了更多的輸出）。

void
QDataStream::setVersion
( int v )

設定資料序列化格式的版本號碼。

如果你只使用目前的版本的Qt，你不需要設定這個版本號碼。

為了提供新的功能，在一些Qt的版本中，一些Qt類的資料流序列化格式變化了。如果你想讀較早版本Qt中建立的資料，或者寫可供較早版本Qt編譯的程式能
夠讀的資料，請使用這個函數來設定QDataStream的序列化格式。

 

• 為了相容Qt 3.0，請使用v
  == 4。
• 為了相容Qt 2.1.x和Qt 2.2.x，請使用v
  == 3。
• 為了相容Qt 2.0.x，請使用v
  == 2。
• 為了相容Qt 1.x，請使用v
  == 1。

 

也可以參考version().

void
QDataStream::unsetDevice
()

清除IO裝置。這個和調用setDevice(
0 )一樣。

也可以參考device()
和setDevice()。

int
QDataStream::version ()
const

返回資料序列化格式的版本號碼。
在Qt 3.0中，這個版本號碼為4。

也可以參考setVersion()。

QDataStream &

QDataStream::writeBytes ( const char * s,
uint len )

寫長度說明符len
和緩衝s
到流中並返迴流的引用。

len
被序列化為一個Q_UINT32，接著的是s
中的len
位元組。注意資料不
是
編碼的。

 

也可以參考writeRawBytes()
和readBytes()。

QDataStream &

QDataStream::writeRawBytes (
const char * s, uint len )

從s
中寫len
位元組到流中並且返迴流的引用。資料不是
編碼的。

 

也可以參考writeBytes()、QIODevice::writeBlock()
和readRawBytes()。