Static utility class for reading and writing circuit and waveform files. More...

#include <Serialization.h>

Classes
struct	Preamble
	Result of reading a .panda file preamble (header + dolphin + rect + metadata). More...

Static Public Member Functions
static void	copyPandaFile (const QFileInfo &srcPath, const QFileInfo &destPath, QSet< QString > *visited=nullptr, int depth=0)
	Copies a .panda file and its file-backed IC dependencies to destPath.
static void	createVersionedBackup (const QString &fileName, const QVersionNumber &version)
	Copies fileName to a versioned sidecar before overwriting it during migration.
static QList< QGraphicsItem * >	deserialize (QDataStream &stream, SerializationContext &context)
	Deserializes items from stream until the stream is exhausted.
static QMap< QString, QByteArray >	deserializeBlobRegistry (const QMap< QString, QVariant > &metadata, const QVersionNumber &fileVersion)
	Extracts the embedded IC registry from a metadata map.
static QString	loadDolphinFileName (QDataStream &stream, const QVersionNumber &version)
	Returns the BeWavedDolphin waveform file name stored in stream at version.
static QRectF	loadRect (QDataStream &stream, const QVersionNumber &version)
	Returns the canvas viewport rectangle from the last saved session.
static QMap< QString, QByteArray >	readBoundedBlobMap (QDataStream &stream)
	Reads a `QMap<QString,QByteArray>` from stream with bounds checking.
static QKeySequence	readBoundedKeySequence (QDataStream &stream)
	Reads a QKeySequence from stream, rejecting an implausible/oversized internal key-combination count before QDataStream's default QKeySequence deserialization would reserve() it (a QKeySequence holds at most 4 key combinations, so a larger count can only be a corrupt/crafted stream).
static QMap< QString, QVariant >	readBoundedMetadata (QDataStream &stream)
	Reads the file-level metadata `QMap<QString,QVariant>` from stream without calling `QList::reserve()` with a stream-controlled count.
static QString	readBoundedString (QDataStream &stream)
	Reads a QString from stream, refusing to allocate more bytes than remain in the stream (prevents OOM on fuzz-controlled length fields).
static void	readDolphinHeader (QDataStream &stream)
	Reads and validates the BeWavedDolphin waveform file header.
static QVersionNumber	readPandaHeader (QDataStream &stream)
	Reads and validates the .panda circuit file header; returns the stored version number.
static QByteArray	readPayload (QDataStream &stream, const QVersionNumber &version)
	Reads the remainder of stream's device, decompressing it first if version indicates the compressed-payload format (Rev100+).
static Preamble	readPreamble (QDataStream &stream)
	Reads the full .panda preamble: header, dolphin filename, rect, and metadata (V_4_5+).
static void	serialize (const QList< QGraphicsItem * > &items, QDataStream &stream, SerializationOptions options)
	Serializes items to stream in the current .panda binary format.
static void	serializeBlobRegistry (const QMap< QString, QByteArray > &blobs, QMap< QString, QVariant > &metadata)
	Serializes embedded ICs into a metadata map (sets the "embeddedICs" key).
static QString	typeName (const int type)
	Returns the human-readable element type name for the given type integer.
static void	writeDolphinHeader (QDataStream &stream)
	Writes the BeWavedDolphin waveform file header to stream.
static void	writePandaHeader (QDataStream &stream)
	Writes the .panda circuit file header to stream.
static void	writePayload (QDataStream &stream, const QByteArray &payload)
	Compresses payload (qCompress) and writes it to stream.

Static Public Attributes
static constexpr quint32	MAGIC_HEADER_CIRCUIT = 0x57504346
static constexpr quint32	MAGIC_HEADER_WAVEFORM = 0x57505746

Detailed Description

Static utility class for reading and writing circuit and waveform files.

All I/O passes through a QDataStream; the format is versioned using a magic header followed by the version number. The context object carries per-load state (port map, version, IC directory, optional copy-operation) so that element implementations receive everything they need without global variables.

Definition at line 32 of file Serialization.h.

Member Function Documentation

◆ copyPandaFile()

void Serialization::copyPandaFile	(	const QFileInfo &	srcPath,
		const QFileInfo &	destPath,
		QSet< QString > *	visited = nullptr,
		int	depth = 0 )

static

Copies a .panda file and its file-backed IC dependencies to destPath.

Parameters

srcPath	Source .panda file info.
destPath	Destination .panda file info.
visited	Internal recursion guard; root callers leave this null.
depth	Internal recursion depth; root callers leave this at 0. Throws once a chain of distinct dependency files would recurse past a fixed limit — the visited cycle guard alone doesn't bound a long, non-cyclic chain.

Definition at line 789 of file Serialization.cpp.

References copyPandaFile(), VersionInfo::hasMetadata(), MAGIC_HEADER_CIRCUIT, Serialization::Preamble::metadata, PANDACEPTION, readPreamble(), and Serialization::Preamble::version.

Referenced by ICController::addICFromFile(), copyPandaFile(), and WorkSpace::save().

◆ createVersionedBackup()

void Serialization::createVersionedBackup	(	const QString &	fileName,
		const QVersionNumber &	version )

static

Copies fileName to a versioned sidecar before overwriting it during migration.

Parameters

fileName	Absolute path of the file to back up.
version	The old file-format version (used to build the sidecar name).

The backup name has the form basename.vX.Y.Z.ext (e.g. ic.v4.1.panda). If a backup with that name already exists it is left untouched. Silently logs a warning if the copy fails; does not throw.

Definition at line 697 of file Serialization.cpp.

References PANDACEPTION, and qCDebug.

◆ deserialize()

QList< QGraphicsItem * > Serialization::deserialize	(	QDataStream &	stream,
		SerializationContext &	context )

static

Deserializes items from stream until the stream is exhausted.

Parameters

stream	Source data stream.
context	Per-load context (portMap, version, contextDir).

Returns: List of deserialized QGraphicsItems ready to be added to a scene.

Definition at line 568 of file Serialization.cpp.

References ElementFactory::buildElement(), PANDACEPTION, qCDebug, Connection::Type, GraphicElement::Type, and typeName().

Referenced by SceneDropHandler::handleCloneDrag(), WorkSpace::load(), WorkSpace::loadFromBlob(), and CommandUtils::loadItems().

◆ deserializeBlobRegistry()

QMap< QString, QByteArray > Serialization::deserializeBlobRegistry	(	const QMap< QString, QVariant > &	metadata,
		const QVersionNumber &	fileVersion )

static

Extracts the embedded IC registry from a metadata map.

Parameters

metadata	The file-level metadata map.
fileVersion	The version of the .panda file the metadata was read from. Used to select the correct QDataStream encoding for the blob: files < V_5_0 used an unversioned stream (Qt default at build time); files >= V_5_0 use an explicit Qt_5_12-versioned stream.

Returns an empty map if no blob registry key is present.

Definition at line 749 of file Serialization.cpp.

References VersionInfo::hasVersionedBlobRegistry(), and readBoundedBlobMap().

Referenced by WorkSpace::load(), and WorkSpace::loadFromBlob().

◆ loadDolphinFileName()

QString Serialization::loadDolphinFileName	(	QDataStream &	stream,
		const QVersionNumber &	version )

static

Returns the BeWavedDolphin waveform file name stored in stream at version.

Definition at line 665 of file Serialization.cpp.

References VersionInfo::hasDolphinFilename(), VersionInfo::hasDolphinSentinelFix(), and readBoundedString().

Referenced by WorkSpace::load(), and readPreamble().

◆ loadRect()

QRectF Serialization::loadRect	(	QDataStream &	stream,
		const QVersionNumber &	version )

static

Returns the canvas viewport rectangle from the last saved session.

Definition at line 684 of file Serialization.cpp.

References VersionInfo::hasSceneRect().

Referenced by WorkSpace::load(), and readPreamble().

◆ readBoundedBlobMap()

QMap< QString, QByteArray > Serialization::readBoundedBlobMap ( QDataStream & stream )

static

Reads a QMap<QString,QByteArray> from stream with bounds checking.

Used by the clipboard paste path to safely deserialise the IC blob registry without allowing a fuzz-controlled entry count to cause OOM via QDataStream::operator>>(QMap<QString,QByteArray>&).

Definition at line 297 of file Serialization.cpp.

References PANDACEPTION, and readBoundedString().

Referenced by deserializeBlobRegistry(), and ClipboardManager::paste().

◆ readBoundedKeySequence()

QKeySequence Serialization::readBoundedKeySequence ( QDataStream & stream )

static

Reads a QKeySequence from stream, rejecting an implausible/oversized internal key-combination count before QDataStream's default QKeySequence deserialization would reserve() it (a QKeySequence holds at most 4 key combinations, so a larger count can only be a corrupt/crafted stream).

Definition at line 272 of file Serialization.cpp.

◆ readBoundedMetadata()

QMap< QString, QVariant > Serialization::readBoundedMetadata ( QDataStream & stream )

static

Reads the file-level metadata QMap<QString,QVariant> from stream without calling QList::reserve() with a stream-controlled count.

Qt's built-in operator>> for QList (used internally by QStringList and any other list-valued QVariant) calls reserve(n) before reading a single element, so a fuzz-controlled n causes an immediate multi-GB allocation. This function intercepts the QVariant type tag and dispatches to bounded readers for each supported type (QString, QStringList, QByteArray, and scalar types); unknown types throw PANDACEPTION so the caller rejects the file cleanly.

Definition at line 277 of file Serialization.cpp.

References PANDACEPTION, and readBoundedString().

Referenced by AudioBox::load(), Buzzer::load(), Clock::load(), ConnectionSerializer::load(), Display14::load(), Display16::load(), Display7::load(), IC::load(), InputButton::load(), InputRotary::load(), InputSwitch::load(), Led::load(), Node::load(), TruthTable::load(), WorkSpace::load(), and readPreamble().

◆ readBoundedString()

QString Serialization::readBoundedString ( QDataStream & stream )

static

Reads a QString from stream, refusing to allocate more bytes than remain in the stream (prevents OOM on fuzz-controlled length fields).

Definition at line 267 of file Serialization.cpp.

Referenced by AudioBox::load(), Buzzer::load(), Display14::load(), Display16::load(), Display7::load(), IC::load(), Led::load(), loadDolphinFileName(), readBoundedBlobMap(), readBoundedMetadata(), and readDragDropPayload().

◆ readDolphinHeader()

void Serialization::readDolphinHeader ( QDataStream & stream )

static

Reads and validates the BeWavedDolphin waveform file header.

Parameters

stream Source data stream positioned at the start of the file.

Definition at line 444 of file Serialization.cpp.

References MAGIC_HEADER_WAVEFORM, and PANDACEPTION.

Referenced by DolphinFile::load(), and DolphinClipboard::pasteFromClipboard().

◆ readPandaHeader()

QVersionNumber Serialization::readPandaHeader ( QDataStream & stream )

static

Reads and validates the .panda circuit file header; returns the stored version number.

Definition at line 369 of file Serialization.cpp.

References MAGIC_HEADER_CIRCUIT, and PANDACEPTION.

Referenced by SceneDropHandler::addFromMimeData(), TrashButton::dropEvent(), ClipboardManager::duplicate(), SceneDropHandler::handleCloneDrag(), SceneDropHandler::handleNewElementDrop(), WorkSpace::load(), CommandUtils::loadItems(), ClipboardManager::paste(), readPreamble(), ICRegistry::rollbackElements(), and ChangePortSizeCommand::undo().

◆ readPayload()

QByteArray Serialization::readPayload	(	QDataStream &	stream,
		const QVersionNumber &	version )

static

Reads the remainder of stream's device, decompressing it first if version indicates the compressed-payload format (Rev100+).

Bounds-checks qCompress()'s 4-byte big-endian uncompressed-size header before calling qUncompress(), which otherwise allocates that many bytes unconditionally – a classic decompression-bomb vector for a crafted file claiming an implausible size. Throws PANDACEPTION on an implausible size or on decompression failure (qUncompress() returning a null QByteArray). Returns the raw bytes unchanged for pre-Rev100 files.

Definition at line 330 of file Serialization.cpp.

References VersionInfo::hasCompressedPayload(), and PANDACEPTION_WITH_CONTEXT.

Referenced by WorkSpace::load(), and readPreamble().

◆ readPreamble()

Serialization::Preamble Serialization::readPreamble ( QDataStream & stream )

static

Reads the full .panda preamble: header, dolphin filename, rect, and metadata (V_4_5+).

Definition at line 714 of file Serialization.cpp.

References VersionInfo::hasMetadata(), VersionInfo::hasUnifiedMetadata(), loadDolphinFileName(), loadRect(), Serialization::Preamble::metadata, PANDACEPTION, readBoundedMetadata(), readPandaHeader(), readPayload(), Serialization::Preamble::remainingPayload, and Serialization::Preamble::version.

Referenced by copyPandaFile(), and WorkSpace::loadFromBlob().

◆ serialize()

void Serialization::serialize	(	const QList< QGraphicsItem * > &	items,
		QDataStream &	stream,
		SerializationOptions	options )

static

Serializes items to stream in the current .panda binary format.

Parameters

items	Items to serialize (graphic elements and connections).
stream	Destination data stream.
options	No default – every caller must state whether this builds a genuine .panda file or an in-session snapshot; see SerializationPurpose.

Definition at line 503 of file Serialization.cpp.

References Connection::Type, and GraphicElement::Type.

Referenced by WorkSpace::save(), WorkSpace::save(), and CommandUtils::saveItems().

◆ serializeBlobRegistry()

void Serialization::serializeBlobRegistry	(	const QMap< QString, QByteArray > &	blobs,
		QMap< QString, QVariant > &	metadata )

static

Serializes embedded ICs into a metadata map (sets the "embeddedICs" key).

Definition at line 766 of file Serialization.cpp.

Referenced by WorkSpace::save(), and WorkSpace::save().

◆ typeName()

QString Serialization::typeName ( const int type )

static

Returns the human-readable element type name for the given type integer.

Definition at line 777 of file Serialization.cpp.

Referenced by deserialize().

◆ writeDolphinHeader()

void Serialization::writeDolphinHeader ( QDataStream & stream )

static

Writes the BeWavedDolphin waveform file header to stream.

Parameters

stream Destination data stream.

Definition at line 437 of file Serialization.cpp.

References FormatRev::current, and MAGIC_HEADER_WAVEFORM.

Referenced by DolphinClipboard::copyToClipboard(), and DolphinFile::save().

◆ writePandaHeader()

void Serialization::writePandaHeader ( QDataStream & stream )

static

Writes the .panda circuit file header to stream.

Parameters

stream Destination data stream.

Definition at line 317 of file Serialization.cpp.

References FormatRev::current, and MAGIC_HEADER_CIRCUIT.

Referenced by ICRegistry::captureSnapshot(), ClipboardManager::cloneDrag(), InlineLabelEditor::commit(), ClipboardManager::copy(), ClipboardManager::cut(), ClipboardManager::duplicate(), ElementLabel::mimeData(), InputSwitch::mousePressEvent(), ChangePortSizeCommand::redo(), WorkSpace::save(), CommandUtils::saveItems(), UpdateBlobCommand::UpdateBlobCommand(), UpdateCommand::UpdateCommand(), and ElementEditor::updateElementAppearance().

◆ writePayload()

void Serialization::writePayload	(	QDataStream &	stream,
		const QByteArray &	payload )

static

Compresses payload (qCompress) and writes it to stream.

Used by every SerializationPurpose::PortableFile writer, right after the metadata + elements + connections for a .panda file (or an embedded-IC blob) have been serialized into an in-memory buffer. Paired with readPayload(). Never used for SerializationPurpose::InMemorySnapshot writers (undo stack, clipboard, drag-and-drop) — those keep writing their payload directly, uncompressed, exactly as before.

Definition at line 324 of file Serialization.cpp.

Referenced by WorkSpace::save(), and WorkSpace::save().

Member Data Documentation

◆ MAGIC_HEADER_CIRCUIT

quint32 Serialization::MAGIC_HEADER_CIRCUIT = 0x57504346

staticconstexpr

Definition at line 219 of file Serialization.h.

Referenced by copyPandaFile(), readPandaHeader(), and writePandaHeader().

◆ MAGIC_HEADER_WAVEFORM

quint32 Serialization::MAGIC_HEADER_WAVEFORM = 0x57505746

staticconstexpr

Definition at line 220 of file Serialization.h.

Referenced by readDolphinHeader(), and writeDolphinHeader().

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

Classes

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ copyPandaFile()

◆ createVersionedBackup()

◆ deserialize()

◆ deserializeBlobRegistry()

◆ loadDolphinFileName()

◆ loadRect()

◆ readBoundedBlobMap()

◆ readBoundedKeySequence()

◆ readBoundedMetadata()

◆ readBoundedString()

◆ readDolphinHeader()

◆ readPandaHeader()

◆ readPayload()

◆ readPreamble()

◆ serialize()

◆ serializeBlobRegistry()

◆ typeName()

◆ writeDolphinHeader()

◆ writePandaHeader()

◆ writePayload()

Member Data Documentation

◆ MAGIC_HEADER_CIRCUIT

◆ MAGIC_HEADER_WAVEFORM