Generic file system helper utilities. More...

Functions
QByteArray	readFile (const QString &filePath, QString *errorString, qint64 maxBytes)

size_t	optimalBufferSize (const QString &path)

bool	exists (const QString &path)

QString	joinPath (const QString &dir, const QString &name)

bool	ensureDirectoryExists (const QString &path)

bool	ensureParentExists (const QString &filePath)

bool	copyDirectoryRecursively (const QString &sourcePath, const QString &destPath)

bool	moveFileOrCopy (const QString &sourcePath, const QString &destPath)

bool	atomicWrite (const QString &filePath, const QByteArray &data)

qint64	availableDiskSpace (const QString &path)

bool	hasSufficientDiskSpace (const QString &path, qint64 requiredBytes, double margin)

QString	toLocalPath (const QString &urlOrPath)

QString	toLocalPath (const QUrl &url)

bool	isLocalPath (const QString &urlOrPath)

bool	isQtResource (const QString &path)

QString	computeFileHash (const QString &filePath, QCryptographicHash::Algorithm algorithm)

QString	computeDecompressedFileHash (const QString &filePath, QCryptographicHash::Algorithm algorithm)

QString	computeHash (const QByteArray &data, QCryptographicHash::Algorithm algorithm)

bool	verifyFileHash (const QString &filePath, const QString &expectedHash, QCryptographicHash::Algorithm algorithm)

QString	hashAlgorithmName (QCryptographicHash::Algorithm algorithm)

QString	tempDirectory ()

QString	uniqueTempPath (const QString &templateName)

std::unique_ptr< QTemporaryFile >	createTempFile (const QByteArray &data, const QString &templateName)

std::unique_ptr< QTemporaryFile >	createTempCopy (const QString &sourcePath, const QString &templateName)

bool	replaceFileFromTemp (QTemporaryFile *tempFile, const QString &targetPath, const QString &backupPath)

Variables
constexpr size_t	kBufferSizeMin = 16384
	Minimum buffer size for I/O operations.

constexpr size_t	kBufferSizeMax = 131072
	Maximum buffer size for I/O operations.

constexpr size_t	kBufferSizeDefault = 65536
	Default buffer size when detection unavailable.

constexpr QCryptographicHash::Algorithm	kDefaultHashAlgorithm = QCryptographicHash::Sha256
	Default hash algorithm for checksum operations.

Detailed Description

Generic file system helper utilities.

Function Documentation

◆ atomicWrite()

bool QGCFileHelper::atomicWrite	(	const QString &	filePath,
		const QByteArray &	data
	)

Write data to file atomically (prevents corruption on crash/power loss) Uses QSaveFile internally: writes to temp file, then atomically renames.

Parameters

filePath	Target file path
data	Data to write

Returns: true on success, false on any error (target unchanged on failure)

Definition at line 210 of file QGCFileHelper.cc.

References atomicWrite(), and ensureParentExists().

Referenced by atomicWrite().

◆ availableDiskSpace()

qint64 QGCFileHelper::availableDiskSpace ( const QString & path )

Get available disk space at a path

Parameters

path	Directory or file path to query

Returns: Available bytes, or -1 if unable to determine

Definition at line 245 of file QGCFileHelper.cc.

References availableDiskSpace().

Referenced by availableDiskSpace(), and hasSufficientDiskSpace().

◆ computeDecompressedFileHash()

QString QGCFileHelper::computeDecompressedFileHash	(	const QString &	filePath,
		QCryptographicHash::Algorithm	algorithm = `kDefaultHashAlgorithm`
	)

Compute hash of decompressed file contents Automatically decompresses .gz, .xz, .zst, .bz2, .lz4 files before hashing For uncompressed files, behaves identically to computeFileHash

Parameters

filePath	Path to file (may be compressed)
algorithm	Hash algorithm (default: SHA-256)

Returns: Hash as hex string, or empty string on error

Definition at line 410 of file QGCFileHelper.cc.

References QGCArchiveDeviceBase::close(), computeDecompressedFileHash(), computeFileHash(), QGCCompression::isCompressedFile(), and QGCDecompressDevice::open().

Referenced by computeDecompressedFileHash().

◆ computeFileHash()

QString QGCFileHelper::computeFileHash	(	const QString &	filePath,
		QCryptographicHash::Algorithm	algorithm = `kDefaultHashAlgorithm`
	)

Compute hash of file contents

Parameters

filePath	Path to file (supports Qt resources)
algorithm	Hash algorithm (default: SHA-256)

Returns: Hash as hex string, or empty string on error

Definition at line 387 of file QGCFileHelper.cc.

References computeFileHash().

Referenced by computeDecompressedFileHash(), computeFileHash(), and verifyFileHash().

◆ computeHash()

QString QGCFileHelper::computeHash	(	const QByteArray &	data,
		QCryptographicHash::Algorithm	algorithm = `kDefaultHashAlgorithm`
	)

Compute hash of data

Parameters

data	Data to hash
algorithm	Hash algorithm (default: SHA-256)

Returns: Hash as hex string

Definition at line 450 of file QGCFileHelper.cc.

References computeHash().

Referenced by computeHash().

◆ copyDirectoryRecursively()

bool QGCFileHelper::copyDirectoryRecursively	(	const QString &	sourcePath,
		const QString &	destPath
	)

Copy a directory recursively to a new location

Parameters

sourcePath	Source directory path
destPath	Destination directory path (created if doesn't exist)

Returns: true on success, false if any file/directory copy fails

Definition at line 136 of file QGCFileHelper.cc.

References copyDirectoryRecursively(), ensureDirectoryExists(), and joinPath().

Referenced by copyDirectoryRecursively(), and moveFileOrCopy().

◆ createTempCopy()

std::unique_ptr< QTemporaryFile > QGCFileHelper::createTempCopy	(	const QString &	sourcePath,
		const QString &	templateName = `QString()`
	)

Create a temporary copy of an existing file

Parameters

sourcePath	Path to source file to copy
templateName	Optional file name template (e.g., "backup_XXXXXX.dat")

Returns: Unique pointer to open temp file with copy, or nullptr on error

Definition at line 575 of file QGCFileHelper.cc.

References createTempCopy(), and createTempFile().

Referenced by createTempCopy().

◆ createTempFile()

std::unique_ptr< QTemporaryFile > QGCFileHelper::createTempFile	(	const QByteArray &	data,
		const QString &	templateName = `QString()`
	)

Create a temporary file with specified content The file is automatically removed when the returned QTemporaryFile is destroyed

Parameters

data	Content to write to the temporary file
templateName	Optional file name template (e.g., "myapp_XXXXXX.json")

Returns: Unique pointer to open temp file (positioned at start), or nullptr on error

Definition at line 552 of file QGCFileHelper.cc.

References createTempFile(), and tempDirectory().

Referenced by createTempCopy(), and createTempFile().

◆ ensureDirectoryExists()

bool QGCFileHelper::ensureDirectoryExists ( const QString & path )

Ensure directory exists, creating it if necessary

Parameters

path	Directory path to ensure exists

Returns: true if directory exists or was created successfully

Definition at line 122 of file QGCFileHelper.cc.

References ensureDirectoryExists().

Referenced by copyDirectoryRecursively(), ensureDirectoryExists(), ensureParentExists(), QGClibarchive::extractAnyArchive(), QGClibarchive::extractArchiveAtomic(), QGClibarchive::extractByPattern(), QGClibarchive::extractFromDevice(), QGClibarchive::extractMultipleFiles(), QGClibarchive::extractWithFilter(), and VehicleCameraControl::handleCameraCaptureStatus().

◆ ensureParentExists()

bool QGCFileHelper::ensureParentExists ( const QString & filePath )

Ensure parent directory exists for a file path

Parameters

filePath Path to a file (parent directory will be created if needed)

Returns: true if parent directory exists or was created successfully

Definition at line 131 of file QGCFileHelper.cc.

References ensureDirectoryExists(), and ensureParentExists().

Referenced by atomicWrite(), QGClibarchive::decompressFromDevice(), QGClibarchive::decompressSingleFile(), ensureParentExists(), QGClibarchive::extractByPattern(), QGClibarchive::extractMultipleFiles(), QGClibarchive::extractSingleFile(), QGClibarchive::extractWithFilter(), replaceFileFromTemp(), and QGCFileDownload::start().

◆ exists()

bool QGCFileHelper::exists ( const QString & path )

Check if path exists (handles Qt resources which always "exist" if valid)

Parameters

path	File path or Qt resource path (:/...)

Returns: true if path exists

Definition at line 106 of file QGCFileHelper.cc.

References exists(), and isQtResource().

Referenced by QGCCompression::detectFormat(), exists(), and QGCCompression::validateFileInput().

◆ hashAlgorithmName()

QString QGCFileHelper::hashAlgorithmName ( QCryptographicHash::Algorithm algorithm )

Get human-readable name for hash algorithm

Parameters

algorithm Hash algorithm

Returns: Name like "SHA-256", "MD5", etc.

Definition at line 477 of file QGCFileHelper.cc.

References hashAlgorithmName().

Referenced by hashAlgorithmName().

◆ hasSufficientDiskSpace()

bool QGCFileHelper::hasSufficientDiskSpace	(	const QString &	path,
		qint64	requiredBytes,
		double	margin = `1.1`
	)

Check if there's sufficient disk space for an operation

Parameters

path	Target directory or file path
requiredBytes	Bytes needed for the operation
margin	Extra margin multiplier (default 1.1 = 10% safety margin)

Returns: true if sufficient space available, false otherwise

Definition at line 266 of file QGCFileHelper.cc.

References availableDiskSpace(), and hasSufficientDiskSpace().

Referenced by QGClibarchive::extractAnyArchive(), QGClibarchive::extractArchiveAtomic(), QGClibarchive::extractWithFilter(), and hasSufficientDiskSpace().

◆ isLocalPath()

bool QGCFileHelper::isLocalPath ( const QString & urlOrPath )

Check if URL or path refers to a local file (not network resource)

Parameters

urlOrPath URL string or filesystem path

Returns: true if local file or Qt resource

Definition at line 354 of file QGCFileHelper.cc.

References isLocalPath(), and isQtResource().

Referenced by isLocalPath(), and QGCFileDownload::start().

◆ isQtResource()

bool QGCFileHelper::isQtResource ( const QString & path )

Check if path is a Qt resource path (:/ or qrc://)

Parameters

path	Path to check

Returns: true if Qt resource path

Definition at line 377 of file QGCFileHelper.cc.

References isQtResource().

Referenced by QGCCompression::detectFormatFromFile(), exists(), QGCArchiveDeviceBase::initSourceFromPath(), isLocalPath(), isQtResource(), and QGClibarchive::openArchiveForReading().

◆ joinPath()

QString QGCFileHelper::joinPath	(	const QString &	dir,
		const QString &	name
	)

Join directory and filename with path separator Handles trailing slashes correctly

Parameters

dir	Directory path
name	File or subdirectory name

Returns: Combined path (dir + "/" + name)

Definition at line 111 of file QGCFileHelper.cc.

References joinPath().

Referenced by copyDirectoryRecursively(), QGClibarchive::extractArchiveAtomic(), QGClibarchive::extractByPattern(), QGClibarchive::extractMultipleFiles(), QGClibarchive::extractWithFilter(), and joinPath().

◆ moveFileOrCopy()

bool QGCFileHelper::moveFileOrCopy	(	const QString &	sourcePath,
		const QString &	destPath
	)

Move a file or directory, falling back to copy+delete for cross-filesystem moves

Parameters

sourcePath	Source path (file or directory)
destPath	Destination path

Returns: true on success, false on failure

Definition at line 173 of file QGCFileHelper.cc.

References copyDirectoryRecursively(), and moveFileOrCopy().

Referenced by moveFileOrCopy(), and replaceFileFromTemp().

◆ optimalBufferSize()

size_t QGCFileHelper::optimalBufferSize ( const QString & path = QString() )

Get optimal buffer size for I/O operations (platform-adaptive) Uses filesystem block size when available, with reasonable fallback

Parameters

path	Optional path to query filesystem block size (empty = use root)

Returns: Buffer size in bytes (16KB-128KB range), cached after first call

Definition at line 68 of file QGCFileHelper.cc.

References kBufferSizeDefault, kBufferSizeMax, kBufferSizeMin, and optimalBufferSize().

Referenced by QGClibarchive::openArchiveForReading(), and optimalBufferSize().

◆ readFile()

QByteArray QGCFileHelper::readFile	(	const QString &	filePath,
		QString *	errorString = `nullptr`,
		qint64	maxBytes = `0`
	)

Read file contents with optional automatic decompression Supports transparent decompression of .gz, .xz, .zst, .bz2, .lz4 files Uses QGCCompression::isCompressedFile() for format detection

Parameters

filePath	Path to file (may be compressed or uncompressed)
errorString	Output error message on failure
maxBytes	Maximum bytes to read (0 = unlimited, applies to decompressed size)

Returns: File contents (decompressed if applicable), empty on failure

Definition at line 22 of file QGCFileHelper.cc.

References QGCArchiveDeviceBase::close(), errorString, QGCCompression::isCompressedFile(), QGCDecompressDevice::open(), and readFile().

Referenced by JsonParsing::isJsonFile(), JsonHelper::openInternalQGCJsonFile(), and readFile().

◆ replaceFileFromTemp()

bool QGCFileHelper::replaceFileFromTemp	(	QTemporaryFile *	tempFile,
		const QString &	targetPath,
		const QString &	backupPath = `QString()`
	)

Safely replace a file using write-to-temp-then-rename pattern More control than atomicWrite - uses provided temp file

Parameters

tempFile	Open temp file with new content (will be closed)
targetPath	Final destination path
backupPath	Optional path for backup of original (empty = no backup)

Returns: true on success, false on error (temp file removed on failure)

Definition at line 602 of file QGCFileHelper.cc.

References ensureParentExists(), moveFileOrCopy(), and replaceFileFromTemp().

Referenced by replaceFileFromTemp().

◆ tempDirectory()

QString QGCFileHelper::tempDirectory ( )

Get the system temporary directory path

Returns: Path to system temp directory

Definition at line 529 of file QGCFileHelper.cc.

References tempDirectory().

Referenced by createTempFile(), tempDirectory(), and uniqueTempPath().

◆ toLocalPath() [1/2]

QString QGCFileHelper::toLocalPath ( const QString & urlOrPath )

Convert URL or path string to local filesystem path Handles: file:// URLs, qrc:// URLs (-> :/), and plain paths

Parameters

urlOrPath URL string, QUrl, or filesystem path

Returns: Local path string, or original string if not convertible

Definition at line 296 of file QGCFileHelper.cc.

References toLocalPath().

Referenced by QGCFileDownload::start(), toLocalPath(), and toLocalPath().

◆ toLocalPath() [2/2]

QString QGCFileHelper::toLocalPath ( const QUrl & url )

Definition at line 317 of file QGCFileHelper.cc.

References toLocalPath().

◆ uniqueTempPath()

QString QGCFileHelper::uniqueTempPath ( const QString & templateName = QString() )

Create a unique temporary file path without creating the file Useful for operations that need a temp path but create the file themselves

Parameters

templateName Optional file name template (e.g., "download_XXXXXX.tmp")

Returns: Unique temporary file path

Definition at line 534 of file QGCFileHelper.cc.

References tempDirectory(), and uniqueTempPath().

Referenced by uniqueTempPath().

◆ verifyFileHash()

bool QGCFileHelper::verifyFileHash	(	const QString &	filePath,
		const QString &	expectedHash,
		QCryptographicHash::Algorithm	algorithm = `kDefaultHashAlgorithm`
	)

Verify file matches expected hash

Parameters

filePath	Path to file
expectedHash	Expected hash (hex string, case-insensitive)
algorithm	Hash algorithm (default: SHA-256)

Returns: true if file hash matches expected hash

Definition at line 455 of file QGCFileHelper.cc.

References computeFileHash(), and verifyFileHash().

Referenced by verifyFileHash().

Variable Documentation

◆ kBufferSizeDefault

constexpr size_t QGCFileHelper::kBufferSizeDefault = 65536

constexpr

Default buffer size when detection unavailable.

Definition at line 39 of file QGCFileHelper.h.

Referenced by optimalBufferSize().

◆ kBufferSizeMax

constexpr size_t QGCFileHelper::kBufferSizeMax = 131072

constexpr

Maximum buffer size for I/O operations.

Definition at line 36 of file QGCFileHelper.h.

Referenced by QGClibarchive::deviceReadCallback(), QGClibarchive::deviceSkipCallback(), QGCArchiveDeviceBase::fillBuffer(), optimalBufferSize(), and QGClibarchive::validateArchive().

◆ kBufferSizeMin

constexpr size_t QGCFileHelper::kBufferSizeMin = 16384

constexpr

Minimum buffer size for I/O operations.

Definition at line 33 of file QGCFileHelper.h.

Referenced by optimalBufferSize().

◆ kDefaultHashAlgorithm

constexpr QCryptographicHash::Algorithm QGCFileHelper::kDefaultHashAlgorithm = QCryptographicHash::Sha256

constexpr

Default hash algorithm for checksum operations.

Definition at line 140 of file QGCFileHelper.h.

Functions

Variables

Detailed Description

Function Documentation

◆ atomicWrite()

◆ availableDiskSpace()

◆ computeDecompressedFileHash()

◆ computeFileHash()

◆ computeHash()

◆ copyDirectoryRecursively()

◆ createTempCopy()

◆ createTempFile()

◆ ensureDirectoryExists()

◆ ensureParentExists()

◆ exists()

◆ hashAlgorithmName()

◆ hasSufficientDiskSpace()

◆ isLocalPath()

◆ isQtResource()

◆ joinPath()

◆ moveFileOrCopy()

◆ optimalBufferSize()

◆ readFile()

◆ replaceFileFromTemp()

◆ tempDirectory()

◆ toLocalPath() [1/2]

◆ toLocalPath() [2/2]

◆ uniqueTempPath()

◆ verifyFileHash()

Variable Documentation

◆ kBufferSizeDefault

◆ kBufferSizeMax

◆ kBufferSizeMin

◆ kDefaultHashAlgorithm