QResource Class
QResource 클래스는 리소스에서 직접 데이터를 읽어들이기 위한 인터페이스를 제공합니다. 더 보기...
| 헤더: | #include <QResource> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- 상속된 멤버를 포함한 모든 멤버 목록
- QResource는 입출력 및 네트워킹의 일부입니다.
참고: 이 클래스의 모든 함수는 재진입 가능합니다.
공개 유형
| enum | Compression { NoCompression, ZlibCompression, ZstdCompression } |
공개 함수
| 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 |
정적 공용 멤버
| 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()) |
보호된 함수
상세 설명
QResource는 단일 리소스 엔티티와 관련된 데이터 집합(및 자식 요소)을 나타내는 객체입니다. QResource는 원시 형식의 바이트에 직접 액세스할 수 있게 해줍니다. 이러한 직접 액세스를 통해 버퍼 복사나 간접 참조 없이 데이터를 읽을 수 있습니다. 간접 참조는 리소스 엔티티를 마치 파일인 것처럼 다룰 때 종종 유용하며, 이는 ` QFile`를 사용하여 구현할 수 있습니다. QResource에 포함된 데이터와 자식 요소는 일반적으로 애플리케이션이나 라이브러리에 컴파일되지만, 런타임에 리소스를 로드하는 것도 가능합니다. 실행 시점에 리소스 파일을 로드하면, 해당 파일은 하나의 거대한 데이터 집합으로 로드된 후 리소스 트리에 대한 참조를 통해 조각 단위로 제공됩니다.
QResource는 절대 경로로 로드할 수 있으며, 이 경우 ‘ / ’ 문자로 시작하는 파일 시스템 경로로 처리되거나, ‘ : ’ 문자로 시작하는 리소스 표기법으로 처리됩니다. 또한 QDir::searchPaths()가 반환하는 경로 목록에서 찾을 수 있는 상대 경로의 리소스도 열 수 있습니다.
파일을 나타내는 QResource에는 이를 뒷받침하는 데이터가 있으며, 이 데이터는 압축되어 있을 수 있습니다. 이 경우 실제 데이터에 접근하려면 qUncompress()를 사용해야 합니다. QFile 를 통해 접근할 때는 이 과정이 암시적으로 수행됩니다. 디렉터리를 나타내는 QResource에는 데이터가 없으며 자식 요소만 포함됩니다.
동적 리소스 로딩
리소스는 애플리케이션의 바이너리 파일에서 제외된 채로 두었다가, 실행 시점에 필요할 때 registerResource() 함수를 사용하여 불러올 수 있습니다. registerResource()에 전달되는 리소스 파일은 rcc로 생성된 바이너리 리소스여야 합니다. 바이너리 리소스에 대한 자세한 내용은 Qt 리소스 시스템 문서에서 확인할 수 있습니다.
이는 설정에 따라 변경되거나, 사용자가 편집한 후 다시 생성될 수 있는 대량의 애플리케이션 아이콘 세트를 로드할 때 종종 유용합니다. 리소스는 단일 파일 읽기 작업의 결과로, 또는 메모리 매핑된 파일 형태로 즉시 메모리에 로드됩니다.
이 방식은 단일 파일만 로드되고, 데이터 조각들은 setFileName()에서 요청된 경로를 통해 제공되므로 상당한 성능 향상을 가져올 수 있습니다.
unregisterResource() 함수는 특정 파일에 대한 참조를 제거합니다. 현재 등록 해제된 파일과 관련된 리소스를 참조하는 QResource 객체가 있는 경우, 해당 객체들은 계속 유효하지만 리소스 파일 자체는 리소스 루트에서 제거되므로, 이 리소스 데이터를 가리키는 새로운 QResource는 더 이상 생성할 수 없습니다. 해당 리소스를 가리키는 마지막 QResource가 소멸되면, 리소스 자체는 메모리에서 매핑이 해제됩니다.
손상 및 보안
QResource 클래스는 전달된 파일에 대해 몇 가지 검사를 수행하여 해당 파일이 현재 버전의 Qt에서 지원되는지 확인합니다. 이러한 테스트는 파일 헤더가 컴파일되지 않은 기능(예: Zstandard 압축 해제)을 요청하지 않는지, 또는 파일이 향후 버전의 Qt용이 아닌지 확인하기 위한 것일 뿐입니다. 이 테스트는 파일 전체의 유효성을 확인하는 것은 아닙니다.
출처를 신뢰할 수 없는 파일에는 QResource를 사용해서는 안 됩니다. 애플리케이션은 적어도 애플리케이션 자체나 그 플러그인만큼 신뢰할 수 있는 출처의 리소스 파일만 로드하도록 설계되어야 합니다.
또한 ‘Qt 리소스 시스템(The Qt Resource System)’, QFile, QDir 및 QFileInfo 를참조하십시오 .
멤버 유형 문서
enum QResource::Compression
이 열거형은 compressionAlgorithm()에서 RCC 도구가 페이로드를 압축하는 데 사용한 알고리즘을 나타내는 데 사용됩니다.
| 상수 | 값 | 설명 |
|---|---|---|
QResource::NoCompression | 0 | 내용이 압축되지 않음 |
QResource::ZlibCompression | 1 | 내용은 zlib를 사용하여 압축되며, qUncompress() 함수를 사용하여 압축을 해제할 수 있습니다. |
QResource::ZstdCompression | 2 | 내용은 zstd를 사용하여 압축됩니다. 압축을 풀려면 zstd 라이브러리의 ZSTD_decompress 함수를 사용하십시오. |
compressionAlgorithm()도 참조하십시오 .
멤버 함수 문서
QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())
file 을 가리키는 QResource를 생성합니다. locale 는 리소스 데이터의 특정 현지화 버전을 불러오는 데 사용됩니다.
QFileInfo, QDir::searchPaths(), setFileName() 및 setLocale()도 참조하십시오 .
[noexcept] QResource::~QResource()
QResource 객체의 리소스를 해제합니다.
QString QResource::absoluteFilePath() const
이 QResource 가 나타내는 실제 경로를 반환합니다. 리소스가 QDir::searchPaths()을 통해 발견된 경우, 경로에 해당 정보가 표시됩니다.
fileName()도 참조하십시오 .
[protected] QStringList QResource::children() const
이 디렉토리에 있는 모든 리소스의 목록을 반환합니다. 리소스가 파일을 나타내는 경우 목록은 비어 있습니다.
isDir()도 참조하십시오 .
QResource::Compression QResource::compressionAlgorithm() const
이 리소스가 압축된 경우, 사용된 압축 유형을 반환합니다. 압축되지 않은 경우, 이 함수는 ` QResource::NoCompression`를 반환합니다.
이 함수가 ` QResource::ZlibCompression`을 반환하는 경우, ` qUncompress()` 함수를 사용하여 데이터를 압축 해제할 수 있습니다. Qt 5.13까지는 이것이 유일한 압축 알고리즘이었습니다.
이 함수가 ` QResource::ZstdCompression`을 반환하는 경우, Zstandard 라이브러리 함수(`<zstd.h> ` 헤더)를 사용해야 합니다. Qt는 래퍼를 제공하지 않습니다.
Zstandard 설명서를 참조하십시오.
const uchar *QResource::data() const
이 리소스가 나타내는 읽기 전용 데이터의 일부에 대한 직접 액세스 권한을 반환합니다. 리소스가 압축된 경우, 반환되는 데이터도 압축된 상태입니다. 호출자는 데이터를 압축 해제하거나 uncompressedData()를 사용해야 합니다. 리소스가 디렉터리인 경우, nullptr 가 반환됩니다.
uncompressedData(), size() 및 isFile()도 참조하십시오 .
QString QResource::fileName() const
이 QResource 객체가 나타내는 파일의 전체 경로를, 전달된 그대로 반환합니다.
setFileName() 및 absoluteFilePath()도 참조하십시오 .
[protected] bool QResource::isDir() const
리소스가 디렉터리를 나타내어 그 안에 ` children()`가 포함될 수 있는 경우 ` true `를 반환하고, 파일을 나타내는 경우에는 `false`를 반환합니다.
isFile()도 참조하십시오 .
[protected] bool QResource::isFile() const
리소스가 파일을 나타내며 이에 상응하는 데이터가 있는 경우 true 를 반환하고, 디렉터리를 나타내는 경우 false를 반환합니다.
isDir()도 참조하십시오 .
bool QResource::isValid() const
리소스가 리소스 계층 구조에 실제로 존재하면 ` true `을 반환하고, 그렇지 않으면 `false`를 반환합니다.
QDateTime QResource::lastModified() const
파일이 리소스로 패키징되기 전 마지막으로 수정된 날짜와 시간을 반환합니다.
QLocale QResource::locale() const
QResource 의 데이터를 찾는 데 사용된 로케일을 반환합니다.
setLocale()도 참조하십시오 .
[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())
지정된 rccFileName 을 mapRoot 로 명시된 리소스 트리 내 위치에 등록하고, 파일이 성공적으로 열리면 true 를 반환하며, 그렇지 않으면 false 를 반환합니다.
unregisterResource()도 참조하십시오 .
[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())
지정된 rccData 를 mapRoot 로 명시된 리소스 트리 내 위치에 등록하고, 파일이 성공적으로 열리면 true 를 반환하며, 그렇지 않으면 false 를 반환합니다.
경고: 리소스 데이터를 참조할 수 있는 모든 QFile 의 수명 기간 동안데이터는 유효한 상태를 유지해야 합니다.
unregisterResource()도 참조하십시오 .
void QResource::setFileName(const QString &file)
QResource 를 file 를 가리키도록 설정합니다. file 는 절대 경로일 수 있으며, 이 경우 파일이 직접 열립니다. 상대 경로인 경우 QDir::searchPaths()에서 파일을 찾으려고 시도합니다.
fileName() 및 absoluteFilePath()도 참조하십시오 .
void QResource::setLocale(const QLocale &locale)
QResource 를 설정하여 locale 에 대한 리소스의 로컬라이제이션만 로드하도록 합니다. 특정 로캘에 해당하는 리소스를 찾을 수 없는 경우 C 로캘이 사용됩니다.
locale() 및 setFileName()도 참조하십시오 .
qint64 QResource::size() const
리소스를 뒷받침하는 저장된 데이터의 크기를 반환합니다.
리소스가 압축된 경우, 이 함수는 압축된 데이터의 크기를 반환합니다. 압축되지 않은 크기를 확인하려면 uncompressedSize()를 참조하십시오.
data(), uncompressedSize(), isFile()도 참조하십시오 .
QByteArray QResource::uncompressedData() const
데이터가 압축된 상태로 저장된 경우, 먼저 압축을 해제한 후 리소스 데이터를 반환합니다. 리소스가 디렉터리이거나 압축 해제 중에 오류가 발생하면 null QByteArray 이 반환됩니다.
참고: 데이터가 압축된경우 , 이 함수는 호출될 때마다 압축을 해제합니다. 호출 간에 결과는 캐시되지 않습니다.
참조: uncompressedSize(), size(), compressionAlgorithm(), isFile().
qint64 QResource::uncompressedSize() const
이 리소스에 포함된 데이터의 크기를 반환합니다. 데이터가 압축되지 않은 경우, 이 함수는 size()과 동일한 결과를 반환합니다. 데이터가 압축된 경우, 이 함수는 저장된 스트림에서 원본 비압축 데이터의 크기를 추출합니다.
size(), uncompressedData() 및 isFile()도 참조하십시오 .
[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
지정된 rccFileName 에 대한 리소스를 mapRoot 로 지정된 리소스 트리 위치에서 등록 해제하며, 리소스가 성공적으로 언로드되고 해당 리소스에 대한 참조가 존재하지 않으면 true 를 반환하고, 그렇지 않으면 false 를 반환합니다.
registerResource()도 참조하십시오 .
[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())
지정된 rccData 에 대한 리소스를 mapRoot 로 지정된 리소스 트리 위치에서 등록 해제하며, 리소스가 성공적으로 언로드되고 해당 리소스에 대한 참조가 존재하지 않을 경우 true 을 반환하고, 그렇지 않은 경우 false 을 반환합니다.
registerResource()도 참조하십시오 .
© 2026 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.