DataStream Class Reference

Binary stream for structured, portable serialization. More...

#include <datastream.h>

Public Types
enum	ByteOrder { BigEndian , LittleEndian }
	Byte order for multi-byte values. More...
enum	Status { Ok , ReadPastEnd , ReadCorruptData , WriteFailed }
	Stream status codes. More...
enum	TypeId : uint8_t {   TypeInt8 = 0x01 , TypeUInt8 = 0x02 , TypeInt16 = 0x03 , TypeUInt16 = 0x04 ,   TypeInt32 = 0x05 , TypeUInt32 = 0x06 , TypeInt64 = 0x07 , TypeUInt64 = 0x08 ,   TypeFloat = 0x09 , TypeDouble = 0x0A , TypeBool = 0x0B , TypeString = 0x0C ,   TypeBuffer = 0x0D , TypeVariant = 0x0E }
	Type identifiers written before each value. More...

Public Member Functions
	DataStream (IODevice *device)
	Constructs a DataStream on an IODevice without writing or reading a header.
	~DataStream ()=default
	Destructor.
void	setByteOrder (ByteOrder order)
	Sets the byte order for multi-byte value serialization.
ByteOrder	byteOrder () const
	Returns the current byte order.
uint16_t	version () const
	Returns the wire format version read from the header.
Status	status () const
	Returns the current stream status.
void	resetStatus ()
	Resets the stream status to Ok.
bool	atEnd () const
	Returns true if the read/write position is at the end.
IODevice *	device () const
	Returns the underlying IODevice.
DataStream &	operator<< (int8_t val)
	Writes an int8_t.
DataStream &	operator<< (uint8_t val)
	Writes a uint8_t.
DataStream &	operator<< (int16_t val)
	Writes an int16_t.
DataStream &	operator<< (uint16_t val)
	Writes a uint16_t.
DataStream &	operator<< (int32_t val)
	Writes an int32_t.
DataStream &	operator<< (uint32_t val)
	Writes a uint32_t.
DataStream &	operator<< (int64_t val)
	Writes an int64_t.
DataStream &	operator<< (uint64_t val)
	Writes a uint64_t.
DataStream &	operator<< (float val)
	Writes a float (IEEE 754).
DataStream &	operator<< (double val)
	Writes a double (IEEE 754).
DataStream &	operator<< (bool val)
	Writes a bool (as uint8_t: 0 or 1).
DataStream &	operator<< (const String &val)
	Writes a String as length-prefixed UTF-8.
DataStream &	operator<< (const Buffer &val)
	Writes a Buffer as length-prefixed raw bytes.
DataStream &	operator<< (const Variant &val)
	Writes a Variant as type tag + value.
DataStream &	operator>> (int8_t &val)
	Reads an int8_t.
DataStream &	operator>> (uint8_t &val)
	Reads a uint8_t.
DataStream &	operator>> (int16_t &val)
	Reads an int16_t.
DataStream &	operator>> (uint16_t &val)
	Reads a uint16_t.
DataStream &	operator>> (int32_t &val)
	Reads an int32_t.
DataStream &	operator>> (uint32_t &val)
	Reads a uint32_t.
DataStream &	operator>> (int64_t &val)
	Reads an int64_t.
DataStream &	operator>> (uint64_t &val)
	Reads a uint64_t.
DataStream &	operator>> (float &val)
	Reads a float (IEEE 754).
DataStream &	operator>> (double &val)
	Reads a double (IEEE 754).
DataStream &	operator>> (bool &val)
	Reads a bool.
DataStream &	operator>> (String &val)
	Reads a String from length-prefixed UTF-8.
DataStream &	operator>> (Buffer &val)
	Reads a Buffer from length-prefixed raw bytes.
DataStream &	operator>> (Variant &val)
	Reads a Variant from type tag + value.
ssize_t	readRawData (void *buf, size_t len)
	Reads raw bytes from the stream.
ssize_t	writeRawData (const void *buf, size_t len)
	Writes raw bytes to the stream.
ssize_t	skipRawData (size_t len)
	Skips over raw bytes in the stream without reading them.

Static Public Member Functions
static DataStream	createWriter (IODevice *device)
	Constructs a DataStream for writing on an IODevice.
static DataStream	createReader (IODevice *device)
	Constructs a DataStream for reading from an IODevice.

Static Public Attributes
static constexpr uint16_t	CurrentVersion = 1
	Current wire format version.
static constexpr uint8_t	Magic [4] = { 0x50, 0x4D, 0x44, 0x53 }
	Magic bytes identifying a DataStream ("PMDS").

Detailed Description

Binary stream for structured, portable serialization.

DataStream provides a Qt-style interface for reading and writing binary data in a portable, byte-order-aware format. It operates exclusively over an IODevice. For in-memory serialization, use BufferIODevice as the underlying device.

Primary use cases include ObjectBase::saveState()/loadState(), file format I/O, and network protocol encoding.

Wire format

Every DataStream begins with a header: a 4-byte magic number (0x50 0x4D 0x44 0x53, ASCII "PMDS") followed by a uint16_t version number in big-endian byte order. The version identifies the wire format so that future changes remain backward-compatible. The current version is 1.

After the header, each value is preceded by a one-byte TypeId tag that identifies the type. On read, the tag is validated against the expected type; a mismatch sets the status to ReadCorruptData. This makes streams self-describing and catches type mismatches early.

Value encoding:

• Multi-byte integers are byte-order controlled via setByteOrder(), defaulting to big-endian (network byte order).
• Strings are stored as a uint32_t byte-count prefix followed by UTF-8 encoded bytes (no null terminator).
• Buffers are stored as a uint32_t byte-count prefix followed by raw bytes.
• Floats and doubles use IEEE 754, byte-swapped if needed.

Extensibility

User types can be serialized by implementing free-standing operator<<(DataStream &, const MyType &) and

Example

// Write to a buffer
BufferIODevice device;
device.open(IODevice::WriteOnly);
DataStream writer = DataStream::createWriter(&device);
writer << int32_t(42) << String("hello") << true;
 
// Read it back
device.seek(0);
DataStream reader = DataStream::createReader(&device);
int32_t num; String str; bool flag;
reader >> num >> str >> flag;

operator>>(DataStream &, MyType &).

Member Enumeration Documentation

ByteOrder

enum DataStream::ByteOrder

Byte order for multi-byte values.

Enumerator
BigEndian	Network byte order (default).
LittleEndian	Intel/ARM byte order.

Status

enum DataStream::Status

Stream status codes.

Enumerator
Ok	No error.
ReadPastEnd	Attempted to read beyond available data.
ReadCorruptData	Data format is invalid.
WriteFailed	A write operation failed.

TypeId

enum DataStream::TypeId : uint8_t

Type identifiers written before each value.

Every operator<< writes a one-byte TypeId before the payload. Every operator>> reads and validates it. A mismatch sets status to ReadCorruptData.

Raw byte methods (readRawData, writeRawData, skipRawData) do NOT write or expect type tags — they are unframed.

Enumerator
TypeInt8	int8_t
TypeUInt8	uint8_t
TypeInt16	int16_t
TypeUInt16	uint16_t
TypeInt32	int32_t
TypeUInt32	uint32_t
TypeInt64	int64_t
TypeUInt64	uint64_t
TypeFloat	float (IEEE 754)
TypeDouble	double (IEEE 754)
TypeBool	bool (as uint8_t)
TypeString	Length-prefixed UTF-8 String.
TypeBuffer	Length-prefixed raw bytes.
TypeVariant	Type-tagged Variant.

Constructor & Destructor Documentation

DataStream()

DataStream::DataStream ( IODevice *  device )

explicit

Constructs a DataStream on an IODevice without writing or reading a header.

This is a low-level constructor for cases where the caller manages the header externally or the stream is used for raw binary I/O without framing.

Parameters

device

The IODevice to operate on.

Member Function Documentation

atEnd()

bool DataStream::atEnd

(

)

const

Returns true if the read/write position is at the end.

Returns

True if at end of data.

byteOrder()

ByteOrder DataStream::byteOrder ( ) const

inline

Returns the current byte order.

Returns

The byte order.

createReader()

static DataStream DataStream::createReader ( IODevice *  device )

static

Constructs a DataStream for reading from an IODevice.

The device must already be open for reading. The header (magic + version) is read and validated immediately. If the header is missing or invalid, status() will be set to ReadCorruptData.

Parameters

device

The IODevice to read from.

createWriter()

static DataStream DataStream::createWriter ( IODevice *  device )

static

Constructs a DataStream for writing on an IODevice.

The device must already be open for writing. A header (magic + version) is written immediately. If the write fails, status() will reflect the error.

Parameters

device

The IODevice to write to.

device()

IODevice * DataStream::device ( ) const

inline

Returns the underlying IODevice.

Returns

The device pointer.

readRawData()

ssize_t DataStream::readRawData	(	void *	buf,
		size_t	len
	)

Reads raw bytes from the stream.

Parameters

buf	Destination buffer.
len	Number of bytes to read.

Returns

The number of bytes actually read, or -1 on error.

setByteOrder()

void DataStream::setByteOrder ( ByteOrder  order )

inline

Sets the byte order for multi-byte value serialization.

Parameters

order

The byte order to use.

skipRawData()

ssize_t DataStream::skipRawData

(

size_t

len

)

Skips over raw bytes in the stream without reading them.

Parameters

len	Number of bytes to skip.

Returns

The number of bytes actually skipped, or -1 on error.

status()

Status DataStream::status ( ) const

inline

Returns the current stream status.

Returns

The status code.

version()

uint16_t DataStream::version ( ) const

inline

Returns the wire format version read from the header.

For writers, this is always CurrentVersion. For readers, this is the version found in the stream header. For streams constructed without a header, this is 0.

Returns

The version number.

writeRawData()

ssize_t DataStream::writeRawData	(	const void *	buf,
		size_t	len
	)

Writes raw bytes to the stream.

Parameters

buf	Source buffer.
len	Number of bytes to write.

Returns

The number of bytes actually written, or -1 on error.

---

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

• include/promeki/core/datastream.h