Class FileUtils

Inherits the following classes: QObject

Public Functions

Type	Name
	FileUtils (QObject * parent=nullptr)
Q_INVOKABLE void	addImageMetadata (const QString & imagePath, const GnssPositionInformation & positionInformation)
Q_INVOKABLE void	addImageStamp (const QString & imagePath, const QString & text, const QString & textFormat=QString(), Qgis::TextHorizontalAlignment horizontalAlignment=Qgis::TextHorizontalAlignment::Left, const QString & imageDecoration=QString())
Q_INVOKABLE void	restrictImageSize (const QString & imagePath, int maximumWidthHeight)
	~FileUtils () = default

Public Static Functions

Type	Name
Q_INVOKABLE QString	absolutePath (const QString & filePath) Returns the absolute path of the folder containing the filePath .
bool	copyRecursively (const QString & sourceFolder, const QString & destFolder, QgsFeedback * feedback=nullptr, bool wipeDestFolder=true)
Q_INVOKABLE QVariantMap	deleteFiles (const QStringList & filePaths)
Q_INVOKABLE QByteArray	fileChecksum (const QString & fileName, const QCryptographicHash::Algorithm hashAlgorithm)
Q_INVOKABLE QString	fileEtag (const QString & fileName, int partSize=8 1024 1024)
Q_INVOKABLE bool	fileExists (const QString & filePath) Returns true if the filePath exists (false if it's a directory)
Q_INVOKABLE QString	fileName (const QString & filePath) Returns the filename of a filePath - if no file name exists it's empty.
Q_INVOKABLE QString	fileSuffix (const QString & filePath) Returns the suffix (extension)
Q_INVOKABLE QVariantMap	getFileInfo (const QString & filePath, bool fetchContent=false)
Q_INVOKABLE bool	isDeletable (const QString & filePath)
Q_INVOKABLE bool	isImageMimeTypeSupported (const QString & mimeType) Returns TRUE if the provided mimetype is a supported image.
bool	isWithinProjectDirectory (const QString & filePath)
Q_INVOKABLE QString	mimeTypeName (const QString & filePath) Returns the mimetype of a filepath as string.
Q_INVOKABLE QByteArray	readFileContent (const QString & filePath)
Q_INVOKABLE QString	representFileSize (qint64 bytes) Returns a human-friendly size from bytes.
Q_INVOKABLE QString	sanitizeFilePath (const QString & filePath, const QString & replacement=QLatin1String("_")) Tries to convert the given filePath with path to a cross OS valid file name with path.
Q_INVOKABLE QString	sanitizeFilePathPart (const QString & filePathPart, const QString & replacement=QLatin1String("_")) Tries to convert the given filePathPart to a cross OS valid file name part.
bool	unzip (const QString & zipFilename, const QString & dir, QStringList & files, bool checkConsistency)
Q_INVOKABLE bool	writeFileContent (const QString & filePath, const QByteArray & content)

Public Functions Documentation

function FileUtils

explicit FileUtils::FileUtils (
    QObject * parent=nullptr
)

function addImageMetadata

Q_INVOKABLE void FileUtils::addImageMetadata (
    const QString & imagePath,
    const GnssPositionInformation & positionInformation
)

Adds positioning metadata to a given image.

Parameters:

imagePath the image path
positionInformation the GNSS position information used to add metadata details

function addImageStamp

Q_INVOKABLE void FileUtils::addImageStamp (
    const QString & imagePath,
    const QString & text,
    const QString & textFormat=QString(),
    Qgis::TextHorizontalAlignment horizontalAlignment=Qgis::TextHorizontalAlignment::Left,
    const QString & imageDecoration=QString()
)

Prints details to a given image.

Parameters:

imagePath the image path
text the details text
project an optional project from which custom stamping settings will be retrieved

function restrictImageSize

Q_INVOKABLE void FileUtils::restrictImageSize (
    const QString & imagePath,
    int maximumWidthHeight
)

Insures that a given image's width and height are restricted to a maximum size.

Parameters:

imagePath the image file path
maximumWidthHeight the maximum width and height size

function ~FileUtils

FileUtils::~FileUtils () = default

Public Static Functions Documentation

function absolutePath

Returns the absolute path of the folder containing the filePath .

static Q_INVOKABLE QString FileUtils::absolutePath (
    const QString & filePath
)

function copyRecursively

static bool FileUtils::copyRecursively (
    const QString & sourceFolder,
    const QString & destFolder,
    QgsFeedback * feedback=nullptr,
    bool wipeDestFolder=true
)

function deleteFiles

static Q_INVOKABLE QVariantMap FileUtils::deleteFiles (
    const QStringList & filePaths
)

Deletes a list of files with security validation. Only deletes files that pass isDeletable() checks and are within the project or cloud directories.

Parameters:

filePaths List of file paths to delete

Returns:

A map with file paths as keys and boolean success status as values

function fileChecksum

static Q_INVOKABLE QByteArray FileUtils::fileChecksum (
    const QString & fileName,
    const QCryptographicHash::Algorithm hashAlgorithm
)

Returns the checksum of a file. An empty QByteArray will be returned if it cannot be calculated.

Parameters:

fileName file name to get checksum of
hashAlgorithm hash algorithm (md5, sha1, sha256 etc)

Returns:

QByteArray checksum value

function fileEtag

static Q_INVOKABLE QString FileUtils::fileEtag (
    const QString & fileName,
    int partSize=8 *1024 *1024
)

Returns an Object Storage (S3) ETag of a file. An empty string will be returned if it cannot be calculated.

Parameters:

fileName file name to get checksum of
partSize maximum size used to divide the file content into parts

Returns:

QString Etag value

function fileExists

Returns true if the filePath exists (false if it's a directory)

static Q_INVOKABLE bool FileUtils::fileExists (
    const QString & filePath
)

function fileName

Returns the filename of a filePath - if no file name exists it's empty.

static Q_INVOKABLE QString FileUtils::fileName (
    const QString & filePath
)

function fileSuffix

Returns the suffix (extension)

static Q_INVOKABLE QString FileUtils::fileSuffix (
    const QString & filePath
)

function getFileInfo

static Q_INVOKABLE QVariantMap FileUtils::getFileInfo (
    const QString & filePath,
    bool fetchContent=false
)

Gets detailed information about a file including MD5 hash and metadata. Optionally includes the file content when fetchContent is true. This is useful for file validation, caching, and efficient file handling in QML.

Parameters:

filePath The path to the file
fetchContent Whether to include the file content in the returned information (default: false)

Returns:

A map containing file metadata and optionally its content

function isDeletable

static Q_INVOKABLE bool FileUtils::isDeletable (
    const QString & filePath
)

Checks if a file can be safely deleted. Security checks: * File must be within application or cloud directories * Only allows deletion of specific file types * Prevents deletion of folders, project files

Parameters:

filePath The path to check for deletion eligibility

Returns:

True if the file can be safely deleted, false otherwise

function isImageMimeTypeSupported

Returns TRUE if the provided mimetype is a supported image.

static Q_INVOKABLE bool FileUtils::isImageMimeTypeSupported (
    const QString & mimeType
)

function isWithinProjectDirectory

static bool FileUtils::isWithinProjectDirectory (
    const QString & filePath
)

Checks if a file path is securely within the current project directory. Security measures: * Prevents directory traversal attacks using path normalization * Handles symbolic links that could escape project boundaries * Supports cross-platform path comparisons (Windows, macOS, Linux, Android, iOS) * Validates non-existent files safely for write operations * Prevents partial directory matching by enforcing complete path containment

Parameters:

filePath The path to check

Returns:

True if the path is safely within the current project directory

function mimeTypeName

Returns the mimetype of a filepath as string.

static Q_INVOKABLE QString FileUtils::mimeTypeName (
    const QString & filePath
)

function readFileContent

static Q_INVOKABLE QByteArray FileUtils::readFileContent (
    const QString & filePath
)

Reads the entire content of a file and returns it as a byte array.

Parameters:

filePath The path to the file to be read

Returns:

The file content as a QByteArray

function representFileSize

Returns a human-friendly size from bytes.

static Q_INVOKABLE QString FileUtils::representFileSize (
    qint64 bytes
)

function sanitizeFilePath

Tries to convert the given filePath with path to a cross OS valid file name with path.

static Q_INVOKABLE QString FileUtils::sanitizeFilePath (
    const QString & filePath,
    const QString & replacement=QLatin1String("_")
)

function sanitizeFilePathPart

Tries to convert the given filePathPart to a cross OS valid file name part.

static Q_INVOKABLE QString FileUtils::sanitizeFilePathPart (
    const QString & filePathPart,
    const QString & replacement=QLatin1String("_")
)

function unzip

static bool FileUtils::unzip (
    const QString & zipFilename,
    const QString & dir,
    QStringList & files,
    bool checkConsistency
)

Unzip a zip file in an output directory.

Parameters:

zip The zip filename
dir The output directory
files The absolute path of unzipped files
checkConsistency Perform additional stricter consistency checks on the archive, and error if they fail (since QGIS 3.30)

Returns:

FALSE if the zip filename does not exist, the output directory does not exist or is not writable.

function writeFileContent

static Q_INVOKABLE bool FileUtils::writeFileContent (
    const QString & filePath,
    const QByteArray & content
)

Writes content to a file.

Parameters:

filePath The path to the file to be written
content The content to write to the file

Returns:

True if the write operation was successful, false otherwise

Note:

Platform restrictions apply: * On Android: Writing is only permitted within the app's internal storage or properly requested scoped storage locations. * On iOS: Writing is restricted to the app's sandbox. * Use PlatformUtilities.applicationDirectory() to get a safe write location.

The documentation for this class was generated from the following file src/core/utils/fileutils.h