KPackage 5.109.0
|
object representing an installed package More...
#include <KPackage/Package>
Public Types | |
enum | JobError { RootCreationError = KJob::UserDefinedError + 1 , PackageFileNotFoundError , UnsupportedArchiveFormatError , PackageOpenError , MetadataFileMissingError , PluginNameMissingError , PluginNameInvalidError , UpdatePackageTypeMismatchError , OldVersionRemovalError , NewerVersionAlreadyInstalledError , PackageAlreadyInstalledError , PackageMoveError , PackageCopyError , PackageUninstallError } |
Error codes for the install/update/remove jobs. More... | |
Public Member Functions | |
Package (const Package &other) | |
Copy constructor. | |
Package (PackageStructure *structure=nullptr) | |
Default constructor. | |
void | addDirectoryDefinition (const QByteArray &key, const QString &path, const QString &name=QString()) |
Adds a directory to the structure of the package. | |
void | addFileDefinition (const QByteArray &key, const QString &path, const QString &name=QString()) |
Adds a file to the structure of the package. | |
bool | allowExternalPaths () const |
QString | contentsHash () const |
QStringList | contentsPrefixPaths () const |
QByteArray | cryptographicHash (QCryptographicHash::Algorithm algorithm) const |
QString | defaultPackageRoot () const |
QList< QByteArray > | directories () const |
QStringList | entryList (const QByteArray &key) const |
Get the list of files of a given type. | |
KPackage::Package | fallbackPackage () const |
QString | filePath (const QByteArray &key, const QString &filename=QString()) const |
Get the path to a given file based on the key and an optional filename. | |
QList< QByteArray > | files () const |
QUrl | fileUrl (const QByteArray &key, const QString &filename=QString()) const |
Get the url to a given file based on the key and an optional filename, is the file:// or qrc:// format Example: finding the main script in a scripting package: filePath("mainscript") | |
bool | hasValidStructure () const |
KJob * | install (const QString &sourcePackage, const QString &packageRoot=QString()) |
Installs a package matching this package structure. | |
bool | isRequired (const QByteArray &key) const |
bool | isValid () const |
KPluginMetaData | metadata () const |
QStringList | mimeTypes (const QByteArray &key) const |
QString | name (const QByteArray &key) const |
Package & | operator= (const Package &rhs) |
Assignment operator. | |
const QString | path () const |
void | removeDefinition (const QByteArray &key) |
Removes a definition from the structure of the package. | |
QList< QByteArray > | requiredDirectories () const |
QList< QByteArray > | requiredFiles () const |
void | setAllowExternalPaths (bool allow) |
Sets whether or not external paths/symlinks can be followed by a package. | |
void | setContentsPrefixPaths (const QStringList &prefixPaths) |
Sets the prefixes that all the contents in this package should appear under. | |
void | setDefaultMimeTypes (const QStringList &mimeTypes) |
Defines the default mimeTypes for any definitions that do not have associated mimeTypes. | |
void | setDefaultPackageRoot (const QString &packageRoot) |
Sets preferred package root. | |
void | setFallbackPackage (const KPackage::Package &package) |
Sets the fallback package root path If a file won't be found in this package, it will search it in the package with the same structure identified by path It is intended to be used by the packageStructure. | |
void | setMetadata (const KPluginMetaData &data) |
Sets the metadata for the KPackage. | |
void | setMimeTypes (const QByteArray &key, const QStringList &mimeTypes) |
Define mimeTypes for a given part of the structure The path must already have been added using addDirectoryDefinition or addFileDefinition. | |
void | setPath (const QString &path) |
Sets the path to the root of this package. | |
void | setRequired (const QByteArray &key, bool required) |
Sets whether or not a given part of the structure is required or not. | |
KJob * | uninstall (const QString &packageName, const QString &packageRoot) |
Uninstalls a package matching this package structure. | |
KJob * | update (const QString &sourcePackage, const QString &packageRoot=QString()) |
Updates a package matching this package structure. | |
object representing an installed package
Package defines what is in a package and provides easy access to the contents.
To define a package, one might write the following code:
One may also choose to create a subclass of PackageStructure and include the setup in the constructor.
Either way, Package creates a self-documenting contract between the packager and the application without exposing package internals such as actual on-disk structure of the package or requiring that all contents be explicitly known ahead of time.
Subclassing PackageStructure does have provide a number of potential const benefits:
Error codes for the install/update/remove jobs.
|
explicit |
KPackage::Package::Package | ( | const Package & | other | ) |
Copy constructor.
void KPackage::Package::addDirectoryDefinition | ( | const QByteArray & | key, |
const QString & | path, | ||
const QString & | name = QString() |
||
) |
Adds a directory to the structure of the package.
It is added as a not-required element with no associated mimeTypes.
Starting in 4.6, if an entry with the given key already exists, the path is added to it as a search alternative.
key | used as an internal label for this directory |
path | the path within the package for this directory |
name | the user visible (translated) name for the directory, since 5.106 this defaults to an empty string. In KF6, this parameter is removed |
void KPackage::Package::addFileDefinition | ( | const QByteArray & | key, |
const QString & | path, | ||
const QString & | name = QString() |
||
) |
Adds a file to the structure of the package.
It is added as a not-required element with no associated mimeTypes.
Starting in 4.6, if an entry with the given key already exists, the path is added to it as a search alternative.
key | used as an internal label for this file |
path | the path within the package for this file |
name | the user visible (translated) name for the file, since 5.106 this defaults to an empty string. In KF6, this parameter is removed |
bool KPackage::Package::allowExternalPaths | ( | ) | const |
QString KPackage::Package::contentsHash | ( | ) | const |
QStringList KPackage::Package::contentsPrefixPaths | ( | ) | const |
QByteArray KPackage::Package::cryptographicHash | ( | QCryptographicHash::Algorithm | algorithm | ) | const |
QString KPackage::Package::defaultPackageRoot | ( | ) | const |
QList< QByteArray > KPackage::Package::directories | ( | ) | const |
QStringList KPackage::Package::entryList | ( | const QByteArray & | key | ) | const |
Get the list of files of a given type.
fileType | the type of file to look for, as defined in the package structure. |
KPackage::Package KPackage::Package::fallbackPackage | ( | ) | const |
QString KPackage::Package::filePath | ( | const QByteArray & | key, |
const QString & | filename = QString() |
||
) | const |
Get the path to a given file based on the key and an optional filename.
Example: finding the main script in a scripting package: filePath("mainscript")
Example: finding a specific image in the images directory: filePath("images", "myimage.png")
key | the key of the file type to look for, |
filename | optional name of the file to locate within the package |
QList< QByteArray > KPackage::Package::files | ( | ) | const |
QUrl KPackage::Package::fileUrl | ( | const QByteArray & | key, |
const QString & | filename = QString() |
||
) | const |
Get the url to a given file based on the key and an optional filename, is the file:// or qrc:// format Example: finding the main script in a scripting package: filePath("mainscript")
Example: finding a specific image in the images directory: filePath("images", "myimage.png")
key | the key of the file type to look for, |
filename | optional name of the file to locate within the package |
bool KPackage::Package::hasValidStructure | ( | ) | const |
KJob * KPackage::Package::install | ( | const QString & | sourcePackage, |
const QString & | packageRoot = QString() |
||
) |
Installs a package matching this package structure.
By default installs a native KPackage::Package. After the KJob will emitted finished(), if the install went well the Package instance will be guaranteed to have loaded the package just installed, and be valid and usable.
bool KPackage::Package::isRequired | ( | const QByteArray & | key | ) | const |
bool KPackage::Package::isValid | ( | ) | const |
KPluginMetaData KPackage::Package::metadata | ( | ) | const |
QStringList KPackage::Package::mimeTypes | ( | const QByteArray & | key | ) | const |
QString KPackage::Package::name | ( | const QByteArray & | key | ) | const |
const QString KPackage::Package::path | ( | ) | const |
void KPackage::Package::removeDefinition | ( | const QByteArray & | key | ) |
Removes a definition from the structure of the package.
key | the internal label of the file or directory to remove |
QList< QByteArray > KPackage::Package::requiredDirectories | ( | ) | const |
QList< QByteArray > KPackage::Package::requiredFiles | ( | ) | const |
void KPackage::Package::setAllowExternalPaths | ( | bool | allow | ) |
Sets whether or not external paths/symlinks can be followed by a package.
allow | true if paths/symlinks outside of the package should be followed, false if they should be rejected. |
void KPackage::Package::setContentsPrefixPaths | ( | const QStringList & | prefixPaths | ) |
Sets the prefixes that all the contents in this package should appear under.
This defaults to "contents/" and is added automatically between the base path and the entries as defined by the package structure. Multiple entries can be added. In this case each file request will be searched in all prefixes in order, and the first found will be returned.
prefix | paths the directory prefix to use |
void KPackage::Package::setDefaultMimeTypes | ( | const QStringList & | mimeTypes | ) |
Defines the default mimeTypes for any definitions that do not have associated mimeTypes.
Handy for packages with only one or predominantly one file type.
mimeTypes | a list of mimeTypes |
void KPackage::Package::setDefaultPackageRoot | ( | const QString & | packageRoot | ) |
Sets preferred package root.
void KPackage::Package::setFallbackPackage | ( | const KPackage::Package & | package | ) |
Sets the fallback package root path If a file won't be found in this package, it will search it in the package with the same structure identified by path It is intended to be used by the packageStructure.
path | package root path |
void KPackage::Package::setMetadata | ( | const KPluginMetaData & | data | ) |
Sets the metadata for the KPackage.
This overwrites the current metadata. This should be used in case a kpackage gets loaded by name, based on the path a C++ plugin which has embedded metadata.
void KPackage::Package::setMimeTypes | ( | const QByteArray & | key, |
const QStringList & | mimeTypes | ||
) |
Define mimeTypes for a given part of the structure The path must already have been added using addDirectoryDefinition or addFileDefinition.
key | the entry within the package |
mimeTypes | a list of mimeTypes |
void KPackage::Package::setPath | ( | const QString & | path | ) |
Sets the path to the root of this package.
path | an absolute path, or a relative path to the default package root |
void KPackage::Package::setRequired | ( | const QByteArray & | key, |
bool | required | ||
) |
Sets whether or not a given part of the structure is required or not.
The path must already have been added using addDirectoryDefinition or addFileDefinition.
key | the entry within the package |
required | true if this entry is required, false if not |
KJob * KPackage::Package::uninstall | ( | const QString & | packageName, |
const QString & | packageRoot | ||
) |
Uninstalls a package matching this package structure.
KJob * KPackage::Package::update | ( | const QString & | sourcePackage, |
const QString & | packageRoot = QString() |
||
) |
Updates a package matching this package structure.
By default installs a native KPackage::Package. If an older version is already installed, it removes the old one. If the installed one is newer, an error will occur. After the KJob will emitted finished(), if the install went well the Package instance will be guaranteed to have loaded the package just updated, and be valid and usable.