QResource Class
Die Klasse QResource bietet eine Schnittstelle, um direkt aus Ressourcen zu lesen. Mehr...
| Kopfzeile: | #include <QResource> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Liste aller Mitglieder, einschließlich geerbter Mitglieder
- QResource ist Teil von Input/Output und Networking.
Hinweis: Alle Funktionen in dieser Klasse sind reentrant.
Öffentliche Typen
| enum | Compression { NoCompression, ZlibCompression, ZstdCompression } |
Öffentliche Funktionen
| QResource(const QString &file = QString(), const QLocale &locale = QLocale()) | |
| ~QResource() | |
| QString | absoluteFilePath() const |
| QResource::Compression | compressionAlgorithm() const |
| const uchar * | data() const |
| QString | fileName() const |
| bool | isValid() const |
| QDateTime | lastModified() const |
| QLocale | locale() const |
| void | setFileName(const QString &file) |
| void | setLocale(const QLocale &locale) |
| qint64 | size() const |
| QByteArray | uncompressedData() const |
| qint64 | uncompressedSize() const |
Statische öffentliche Mitglieder
| bool | registerResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | registerResource(const uchar *rccData, const QString &mapRoot = QString()) |
| bool | unregisterResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | unregisterResource(const uchar *rccData, const QString &mapRoot = QString()) |
Geschützte Funktionen
Detaillierte Beschreibung
QResource ist ein Objekt, das einen Satz von Daten (und möglicherweise Kinder) repräsentiert, die sich auf eine einzelne Ressourceneinheit beziehen. QResource ermöglicht den direkten Zugriff auf die Bytes in ihrem Rohformat. Auf diese Weise ermöglicht der direkte Zugriff das Lesen von Daten ohne Pufferkopieren oder Umleitung. Indirektion ist oft nützlich, wenn man mit der Ressource-Entität interagiert, als ob es sich um eine Datei handelt; dies kann mit QFile erreicht werden. Die Daten und Kinder hinter einer QResource werden normalerweise in eine Anwendung/Bibliothek kompiliert, aber es ist auch möglich, eine Ressource zur Laufzeit zu laden. Wenn sie zur Laufzeit geladen wird, wird die Ressourcendatei als ein großer Datensatz geladen und dann in Teilen über Referenzen in den Ressourcenbaum ausgegeben.
Eine QResource kann entweder mit einem absoluten Pfad geladen werden, der entweder wie ein Dateisystem behandelt wird, das mit einem / -Zeichen verwurzelt ist, oder in der Ressource-Notation mit einem : -Zeichen verwurzelt ist. Es kann auch eine relative Ressource geöffnet werden, die in der Liste der Pfade gefunden wird, die von QDir::searchPaths() zurückgegeben wird.
Eine QResource, die eine Datei repräsentiert, hat Daten hinter sich; diese Daten können möglicherweise komprimiert sein, in diesem Fall muss qUncompress() verwendet werden, um auf die echten Daten zuzugreifen; dies geschieht implizit, wenn der Zugriff über QFile erfolgt. Eine QResource, die ein Verzeichnis repräsentiert, hat nur Kinder und keine Daten.
Dynamisches Laden von Ressourcen
Eine Ressource kann aus der Binärdatei einer Anwendung ausgelassen werden und zur Laufzeit mit der Funktion registerResource() geladen werden, wenn sie benötigt wird. Die Ressourcendatei, die an registerResource() übergeben wird, muss eine binäre Ressource sein, wie sie von rcc erstellt wurde. Weitere Informationen über binäre Ressourcen finden Sie in der Dokumentation The Qt Resource System.
Dies kann oft nützlich sein, wenn ein großer Satz von Anwendungssymbolen geladen werden soll, die sich je nach Einstellung ändern können, oder die von einem Benutzer bearbeitet und später neu erstellt werden können. Die Ressource wird sofort in den Speicher geladen, entweder als Ergebnis einer einzelnen Datei-Leseoperation oder als eine im Speicher abgebildete Datei.
Dieser Ansatz kann sich als erheblicher Leistungsgewinn erweisen, da nur eine einzige Datei geladen wird und Datenstücke über den in setFileName() angeforderten Pfad ausgegeben werden.
Die Funktion unregisterResource() entfernt einen Verweis auf eine bestimmte Datei. Wenn es QResource-Objekte gibt, die derzeit auf Ressourcen verweisen, die mit der nicht registrierten Datei in Verbindung stehen, sind diese weiterhin gültig, aber die Ressourcendatei selbst wird aus den Ressourcenwurzeln entfernt, und somit kann keine weitere QResource erstellt werden, die auf diese Ressourcendaten zeigt. Die Ressource selbst wird aus dem Speicher entfernt, wenn die letzte QResource, die auf sie zeigt, zerstört wird.
Korruption und Sicherheit
Die QResource-Klasse führt einige Prüfungen an der übergebenen Datei durch, um festzustellen, ob sie von der aktuellen Version von Qt unterstützt wird. Diese Tests dienen nur dazu, zu überprüfen, dass der Datei-Header keine Funktionen (wie z.B. Zstandard-Dekompression) anfordert, die noch nicht einkompiliert wurden, oder dass die Datei nicht aus einer zukünftigen Version von Qt stammt. Sie bestätigen nicht die Gültigkeit der gesamten Datei.
QResource sollte nicht für Dateien verwendet werden, deren Herkunft nicht vertrauenswürdig ist. Anwendungen sollten so konzipiert sein, dass sie versuchen, nur Ressourcendateien zu laden, deren Herkunft mindestens so vertrauenswürdig ist wie die der Anwendung selbst oder ihrer Plugins.
Siehe auch The Qt Resource System, QFile, QDir, und QFileInfo.
Member-Typ-Dokumentation
enum QResource::Compression
Diese Aufzählung wird von compressionAlgorithm() verwendet, um anzugeben, welchen Algorithmus das RCC-Tool zur Komprimierung der Nutzdaten verwendet hat.
| Konstante | Wert | Beschreibung |
|---|---|---|
QResource::NoCompression | 0 | Inhalt ist nicht komprimiert |
QResource::ZlibCompression | 1 | Der Inhalt ist mit zlib komprimiert und kann mit der Funktion qUncompress() dekomprimiert werden. |
QResource::ZstdCompression | 2 | Der Inhalt ist mit zstd komprimiert. Zum Dekomprimieren verwenden Sie die Funktion ZSTD_decompress aus der zstd-Bibliothek. |
Siehe auch compressionAlgorithm().
Dokumentation der Mitgliedsfunktionen
QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())
Konstruiert eine QResource, die auf file verweist. locale wird verwendet, um eine bestimmte Lokalisierung von Ressourcendaten zu laden.
Siehe auch QFileInfo, QDir::searchPaths(), setFileName(), und setLocale().
[noexcept] QResource::~QResource()
Gibt die Ressourcen des Objekts QResource frei.
QString QResource::absoluteFilePath() const
Gibt den tatsächlichen Pfad zurück, den diese QResource repräsentiert. Wenn die Ressource über QDir::searchPaths() gefunden wurde, wird dies im Pfad angegeben.
Siehe auch fileName().
[protected] QStringList QResource::children() const
Gibt eine Liste aller Ressourcen in diesem Verzeichnis zurück. Wenn die Ressource eine Datei darstellt, ist die Liste leer.
Siehe auch isDir().
QResource::Compression QResource::compressionAlgorithm() const
Gibt den Komprimierungstyp zurück, mit dem diese Ressource komprimiert ist, falls vorhanden. Wenn sie nicht komprimiert ist, gibt diese Funktion QResource::NoCompression zurück.
Wenn diese Funktion QResource::ZlibCompression zurückgibt, können Sie die Daten mit der Funktion qUncompress() dekomprimieren. Bis zu Qt 5.13 war dies der einzig mögliche Kompressionsalgorithmus.
Wenn diese Funktion QResource::ZstdCompression zurückgibt, müssen Sie die Funktionen der Zstandard-Bibliothek verwenden (<zstd.h> header). Qt stellt keinen Wrapper zur Verfügung.
Siehe Zstandard-Handbuch.
Siehe auch data() und isFile().
const uchar *QResource::data() const
Gibt direkten Zugriff auf ein Segment schreibgeschützter Daten zurück, das diese Ressource darstellt. Wenn die Ressource komprimiert ist, sind die zurückgegebenen Daten ebenfalls komprimiert. Der Aufrufer muss dann die Daten dekomprimieren oder uncompressedData() verwenden. Wenn die Ressource ein Verzeichnis ist, wird nullptr zurückgegeben.
Siehe auch uncompressedData(), size(), und isFile().
QString QResource::fileName() const
Gibt den vollständigen Pfad zu der Datei zurück, die diese QResource repräsentiert, so wie sie übergeben wurde.
Siehe auch setFileName() und absoluteFilePath().
[protected] bool QResource::isDir() const
Gibt true zurück, wenn die Ressource ein Verzeichnis darstellt und somit children() enthalten kann, false, wenn sie eine Datei darstellt.
Siehe auch isFile().
[protected] bool QResource::isFile() const
Gibt true zurück, wenn die Ressource eine Datei darstellt und somit Daten hinterlegt sind, false, wenn sie ein Verzeichnis darstellt.
Siehe auch isDir().
bool QResource::isValid() const
Gibt true zurück, wenn die Ressource tatsächlich in der Ressourcenhierarchie existiert, andernfalls false.
QDateTime QResource::lastModified() const
Gibt das Datum und die Uhrzeit zurück, zu der die Datei zuletzt geändert wurde, bevor sie in eine Ressource gepackt wurde.
QLocale QResource::locale() const
Gibt das Gebietsschema zurück, das zum Auffinden der Daten für QResource verwendet wurde.
Siehe auch setLocale().
[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())
Registriert die Ressource mit der angegebenen rccFileName an der durch mapRoot angegebenen Stelle im Ressourcenbaum und gibt true zurück, wenn die Datei erfolgreich geöffnet wurde; andernfalls wird false zurückgegeben.
Siehe auch unregisterResource().
[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())
Registriert die Ressource mit der angegebenen rccData an der durch mapRoot angegebenen Stelle im Ressourcenbaum und gibt true zurück, wenn die Datei erfolgreich geöffnet wurde; andernfalls wird false zurückgegeben.
Warnung: Die Daten müssen während der gesamten Lebensdauer aller QFile, die auf die Ressourcendaten verweisen können, gültig bleiben.
Siehe auch unregisterResource().
void QResource::setFileName(const QString &file)
Setzt ein QResource auf file. file kann entweder absolut sein, in diesem Fall wird es direkt geöffnet, wenn es relativ ist, wird versucht, die Datei in QDir::searchPaths() zu finden.
Siehe auch fileName() und absoluteFilePath().
void QResource::setLocale(const QLocale &locale)
Setzt ein QResource, um nur die Lokalisierung der Ressource für locale zu laden. Wenn keine Ressource für die spezifische Locale gefunden wird, wird die C-Locale verwendet.
Siehe auch locale() und setFileName().
qint64 QResource::size() const
Gibt die Größe der gespeicherten Daten zurück, die die Ressource sichern.
Wenn die Ressource komprimiert ist, gibt diese Funktion die Größe der komprimierten Daten zurück. Siehe uncompressedSize() für die unkomprimierte Größe.
Siehe auch data(), uncompressedSize(), und isFile().
QByteArray QResource::uncompressedData() const
Gibt die Ressourcendaten zurück, wobei sie zuerst dekomprimiert werden, wenn die Daten komprimiert gespeichert wurden. Handelt es sich bei der Ressource um ein Verzeichnis oder tritt beim Dekomprimieren ein Fehler auf, wird eine Null zurückgegeben: QByteArray.
Hinweis: Wenn die Daten komprimiert wurden, wird diese Funktion bei jedem Aufruf dekomprimiert. Das Ergebnis wird zwischen den Aufrufen nicht zwischengespeichert.
Siehe auch uncompressedSize(), size(), compressionAlgorithm(), und isFile().
qint64 QResource::uncompressedSize() const
Gibt die Größe der Daten in dieser Ressource zurück. Wenn die Daten nicht komprimiert wurden, gibt diese Funktion das Gleiche zurück wie size(). War dies der Fall, extrahiert diese Funktion die Größe der unkomprimierten Originaldaten aus dem gespeicherten Stream.
Siehe auch size(), uncompressedData(), und isFile().
[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
Hebt die Registrierung der Ressource mit der angegebenen rccFileName an der durch mapRoot angegebenen Stelle im Ressourcenbaum auf und gibt true zurück, wenn die Ressource erfolgreich entladen wurde und keine Referenzen für die Ressource existieren; andernfalls wird false zurückgegeben.
Siehe auch registerResource().
[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())
Hebt die Registrierung der Ressource mit der angegebenen rccData an der durch mapRoot angegebenen Stelle im Ressourcenbaum auf und gibt true zurück, wenn die Ressource erfolgreich entladen wurde und keine Verweise auf die Ressource bestehen; andernfalls wird false zurückgegeben.
Siehe auch registerResource().
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
