KPackage 5.109.0
Public Types | Public Member Functions | List of all members
KPackage::Package

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
 
Packageoperator= (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.
 

Detailed Description

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:

Package package;
package.addDirectoryDefinition("images", "pics/");
QStringList mimeTypes;
mimeTypes << "image/svg" << "image/png" << "image/jpeg";
package.setMimeTypes("images", mimeTypes);
package.addDirectoryDefinition("scripts", "code/");
mimeTypes.clear();
mimeTypes << "text/\*";
package.setMimeTypes("scripts", mimeTypes);
package.addFileDefinition("mainscript", "code/main.js");
package.setRequired("mainscript", true);
object representing an installed package
Definition package.h:67
void addDirectoryDefinition(const QByteArray &key, const QString &path, const QString &name=QString())
Adds a directory to the structure of the package.
void setRequired(const QByteArray &key, bool required)
Sets whether or not a given part of the structure is required or not.
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 addDir...
void addFileDefinition(const QByteArray &key, const QString &path, const QString &name=QString())
Adds a file to the structure of the package.
QStringList mimeTypes(const QByteArray &key) const

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:

Member Enumeration Documentation

◆ JobError

Error codes for the install/update/remove jobs.

Since
5.17
Enumerator
RootCreationError 

Cannot create package root directory.

PackageFileNotFoundError 

The package file does not exist.

UnsupportedArchiveFormatError 

The archive format of the package is not supported.

PackageOpenError 

Can't open the package file for reading.

MetadataFileMissingError 

The package doesn't have a metadata.desktop file.

PluginNameMissingError 

The metadata.desktop file doesn't specify a plugin name.

PluginNameInvalidError 

The plugin name contains characters different from letters, digits, dots and underscores.

UpdatePackageTypeMismatchError 

A package with this plugin name was already installed, but has a different type in the metadata.desktop file.

OldVersionRemovalError 

Failed to remove the old version of the package during an upgrade.

NewerVersionAlreadyInstalledError 

We tried to update, but the same version or a newer one is already installed.

PackageAlreadyInstalledError 

The package is already installed and a normal install (not update) was performed.

PackageMoveError 

Failure to move a package from the system temporary folder to its final destination.

PackageCopyError 

Failure to copy a package folder from somewhere in the filesystem to its final destination.

PackageUninstallError 

Failure to uninstall a package.

Constructor & Destructor Documentation

◆ Package() [1/2]

KPackage::Package::Package ( PackageStructure structure = nullptr)
explicit

Default constructor.

Parameters
structureif a null pointer is passed in, this will creates an empty (invalid) Package; otherwise the structure is allowed to set up the Package's initial layout
Since
4.6

◆ Package() [2/2]

KPackage::Package::Package ( const Package other)

Copy constructor.

Since
4.6

Member Function Documentation

◆ addDirectoryDefinition()

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.

Parameters
keyused as an internal label for this directory
paththe path within the package for this directory
namethe user visible (translated) name for the directory, since 5.106 this defaults to an empty string. In KF6, this parameter is removed

◆ addFileDefinition()

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.

Parameters
keyused as an internal label for this file
paththe path within the package for this file
namethe user visible (translated) name for the file, since 5.106 this defaults to an empty string. In KF6, this parameter is removed

◆ allowExternalPaths()

bool KPackage::Package::allowExternalPaths ( ) const
Returns
true if paths/symlinks outside the package itself should be followed. By default this is set to false for security reasons.

◆ contentsHash()

QString KPackage::Package::contentsHash ( ) const
Returns
a SHA1 hash digest of the contents of the package in hexadecimal form
Since
4.4
Deprecated:
Since 5.21 use cryptographicHash

◆ contentsPrefixPaths()

QStringList KPackage::Package::contentsPrefixPaths ( ) const
Returns
the prefix paths inserted between the base path and content entries, in order of priority. When searching for a file, all paths will be tried in order.
Since
4.6

◆ cryptographicHash()

QByteArray KPackage::Package::cryptographicHash ( QCryptographicHash::Algorithm  algorithm) const
Returns
a hash digest of the contents of the package in hexadecimal form
Since
5.21

◆ defaultPackageRoot()

QString KPackage::Package::defaultPackageRoot ( ) const
Returns
preferred package root. This defaults to kpackage/generic/

◆ directories()

QList< QByteArray > KPackage::Package::directories ( ) const
Returns
all directories registered as part of this Package's structure

◆ entryList()

QStringList KPackage::Package::entryList ( const QByteArray &  key) const

Get the list of files of a given type.

Parameters
fileTypethe type of file to look for, as defined in the package structure.
Returns
list of files by name, suitable for passing to filePath

◆ fallbackPackage()

KPackage::Package KPackage::Package::fallbackPackage ( ) const
Returns
The fallback package root path

◆ filePath()

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")

Parameters
keythe key of the file type to look for,
filenameoptional name of the file to locate within the package
Returns
path to the file on disk. QString() if not found.

◆ files()

QList< QByteArray > KPackage::Package::files ( ) const
Returns
all files registered as part of this Package's structure

◆ fileUrl()

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")

Parameters
keythe key of the file type to look for,
filenameoptional name of the file to locate within the package
Returns
path to the file on disk. QString() if not found.
Since
5.41

◆ hasValidStructure()

bool KPackage::Package::hasValidStructure ( ) const
Returns
true if this package has a valid PackageStructure associatedw it with it. A package may not be valid, but have a valid structure. Useful when dealing with Package objects in a semi-initialized state (e.g. before calling setPath())
Since
5.1

◆ install()

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.

Returns
KJob to track installation progress and result

◆ isRequired()

bool KPackage::Package::isRequired ( const QByteArray &  key) const
Returns
true if the item at path exists and is required

◆ isValid()

bool KPackage::Package::isValid ( ) const
Returns
true if all the required components exist

◆ metadata()

KPluginMetaData KPackage::Package::metadata ( ) const
Returns
the package metadata object.

◆ mimeTypes()

QStringList KPackage::Package::mimeTypes ( const QByteArray &  key) const
Returns
the mimeTypes associated with the path, if any

◆ name()

QString KPackage::Package::name ( const QByteArray &  key) const
Returns
user visible name for the given entry
Deprecated:
Since 5.106, deprecated for lack of usage

◆ operator=()

Package & KPackage::Package::operator= ( const Package rhs)

Assignment operator.

Since
4.6

◆ path()

const QString KPackage::Package::path ( ) const
Returns
the path to the root of this particular package

◆ removeDefinition()

void KPackage::Package::removeDefinition ( const QByteArray &  key)

Removes a definition from the structure of the package.

Since
4.6
Parameters
keythe internal label of the file or directory to remove

◆ requiredDirectories()

QList< QByteArray > KPackage::Package::requiredDirectories ( ) const
Returns
all directories registered as part of this Package's required structure

◆ requiredFiles()

QList< QByteArray > KPackage::Package::requiredFiles ( ) const
Returns
all files registered as part of this Package's required structure

◆ setAllowExternalPaths()

void KPackage::Package::setAllowExternalPaths ( bool  allow)

Sets whether or not external paths/symlinks can be followed by a package.

Parameters
allowtrue if paths/symlinks outside of the package should be followed, false if they should be rejected.

◆ setContentsPrefixPaths()

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.

Parameters
prefixpaths the directory prefix to use
Since
4.6

◆ setDefaultMimeTypes()

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.

Parameters
mimeTypesa list of mimeTypes

◆ setDefaultPackageRoot()

void KPackage::Package::setDefaultPackageRoot ( const QString &  packageRoot)

Sets preferred package root.

◆ setFallbackPackage()

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.

Parameters
pathpackage root path
See also
setPath

◆ setMetadata()

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.

Since
5.88

◆ setMimeTypes()

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.

Parameters
keythe entry within the package
mimeTypesa list of mimeTypes

◆ setPath()

void KPackage::Package::setPath ( const QString &  path)

Sets the path to the root of this package.

Parameters
pathan absolute path, or a relative path to the default package root
Since
4.3

◆ setRequired()

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.

Parameters
keythe entry within the package
requiredtrue if this entry is required, false if not

◆ uninstall()

KJob * KPackage::Package::uninstall ( const QString &  packageName,
const QString &  packageRoot 
)

Uninstalls a package matching this package structure.

Returns
KJob to track removal progress and result

◆ update()

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.

Returns
KJob to track installation progress and result
Since
5.17