KPackage::Package

#include <KPackage/Package>

Public Types
enum	JobError { RootCreationError = KJob::UserDefinedError + 1, PackageFileNotFoundError, UnsupportedArchiveFormatError, PackageOpenError, MetadataFileMissingError, PluginNameMissingError, PluginNameInvalidError, UpdatePackageTypeMismatchError, OldVersionRemovalError, NewerVersionAlreadyInstalledError, PackageAlreadyInstalledError, PackageMoveError, PackageCopyError, PackageUninstallError }

Public Member Functions
	Package (const Package &other)

	Package (PackageStructure *structure=nullptr)

void	addDirectoryDefinition (const QByteArray &key, const QString &path, const QString &name)

void	addFileDefinition (const QByteArray &key, const QString &path, const QString &name)

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

KPackage::Package	fallbackPackage () const

QString	filePath (const QByteArray &key, const QString &filename=QString()) const

QList< QByteArray >	files () const

QUrl	fileUrl (const QByteArray &key, const QString &filename=QString()) const

bool	hasValidStructure () const

KJob *	install (const QString &sourcePackage, const QString &packageRoot=QString())

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)

const QString	path () const

void	removeDefinition (const QByteArray &key)

QList< QByteArray >	requiredDirectories () const

QList< QByteArray >	requiredFiles () const

void	setAllowExternalPaths (bool allow)

void	setContentsPrefixPaths (const QStringList &prefixPaths)

void	setDefaultMimeTypes (const QStringList &mimeTypes)

void	setDefaultPackageRoot (const QString &packageRoot)

void	setFallbackPackage (const KPackage::Package &package)

void	setMetadata (const KPluginMetaData &data)

void	setMimeTypes (const QByteArray &key, const QStringList &mimeTypes)

void	setPath (const QString &path)

void	setRequired (const QByteArray &key, bool required)

KJob *	uninstall (const QString &packageName, const QString &packageRoot)

KJob *	update (const QString &sourcePackage, const QString &packageRoot=QString())

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/", i18n("Images"));
QStringList mimeTypes;
mimeTypes << "image/svg" << "image/png" << "image/jpeg";
package.setMimeTypes("images", mimeTypes);
 
package.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
mimeTypes.clear();
mimeTypes << "text/\*";
package.setMimeTypes("scripts", mimeTypes);
 
package.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
package.setRequired("mainscript", true);

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:

the package can be notified of path changes via the virtual pathChanged() method
the subclass may implement mechanisms to install and remove packages using the virtual install and uninstall methods
subclasses can be compiled as plugins for easy re-use

Definition at line 66 of file package.h.

Member Enumeration Documentation

◆ JobError

enum KPackage::Package::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.

Definition at line 73 of file package.h.

Constructor & Destructor Documentation

◆ Package() [1/2]

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

explicit

Default constructor.

Parameters

structure if 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

Definition at line 35 of file package.cpp.

◆ Package() [2/2]

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

Copy constructor.

Since: 4.6

Definition at line 48 of file package.cpp.

Member Function Documentation

◆ addDirectoryDefinition()

void KPackage::Package::addDirectoryDefinition	(	const QByteArray &	key,
		const QString &	path,
		const QString &	name
	)

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

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

Definition at line 667 of file package.cpp.

◆ addFileDefinition()

void KPackage::Package::addFileDefinition	(	const QByteArray &	key,
		const QString &	path,
		const QString &	name
	)

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

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

Definition at line 691 of file package.cpp.

◆ 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.

Definition at line 189 of file package.cpp.

◆ 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

Definition at line 623 of file package.cpp.

◆ 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

Definition at line 597 of file package.cpp.

◆ 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

Definition at line 629 of file package.cpp.

◆ defaultPackageRoot()

QString KPackage::Package::defaultPackageRoot ( ) const

Returns: preferred package root. This defaults to kpackage/generic/

Definition at line 155 of file package.cpp.

◆ directories()

QList< QByteArray > KPackage::Package::directories ( ) const

Returns: all directories registered as part of this Package's structure

Definition at line 759 of file package.cpp.

◆ entryList()

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

Get the list of files of a given type.

Parameters

fileType the type of file to look for, as defined in the package structure.

Returns: list of files by name, suitable for passing to filePath

Definition at line 410 of file package.cpp.

◆ fallbackPackage()

KPackage::Package KPackage::Package::fallbackPackage ( ) const

Returns: The fallback package root path

Definition at line 180 of file package.cpp.

◆ 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

key	the key of the file type to look for,
filename	optional name of the file to locate within the package

Returns: path to the file on disk. QString() if not found.

Definition at line 319 of file package.cpp.

◆ files()

QList< QByteArray > KPackage::Package::files ( ) const

Returns: all files registered as part of this Package's structure

Definition at line 785 of file package.cpp.

◆ 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

key	the key of the file type to look for,
filename	optional name of the file to locate within the package

Returns: path to the file on disk. QString() if not found.

Since: 5.41

Definition at line 399 of file package.cpp.

◆ 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

Definition at line 70 of file package.cpp.

◆ 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

Definition at line 812 of file package.cpp.

◆ isRequired()

bool KPackage::Package::isRequired ( const QByteArray & key ) const

Returns: true if the item at path exists and is required

Definition at line 131 of file package.cpp.

◆ isValid()

bool KPackage::Package::isValid ( ) const

Returns: true if all the required components exist

Definition at line 75 of file package.cpp.

◆ metadata()

KPluginMetaData KPackage::Package::metadata ( ) const

Returns: the package metadata object.

Definition at line 206 of file package.cpp.

◆ mimeTypes()

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

Returns: the mimeTypes associated with the path, if any

Definition at line 141 of file package.cpp.

◆ name()

QString KPackage::Package::name ( const QByteArray & key ) const

Returns: user visible name for the given entry

Definition at line 121 of file package.cpp.

◆ operator=()

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

Assignment operator.

Since: 4.6

Definition at line 61 of file package.cpp.

◆ path()

const QString KPackage::Package::path ( ) const

Returns: the path to the root of this particular package

Definition at line 592 of file package.cpp.

◆ removeDefinition()

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

Removes a definition from the structure of the package.

Since: 4.6

Parameters

key	the internal label of the file or directory to remove

Definition at line 714 of file package.cpp.

◆ requiredDirectories()

QList< QByteArray > KPackage::Package::requiredDirectories ( ) const

Returns: all directories registered as part of this Package's required structure

Definition at line 772 of file package.cpp.

◆ requiredFiles()

QList< QByteArray > KPackage::Package::requiredFiles ( ) const

Returns: all files registered as part of this Package's required structure

Definition at line 798 of file package.cpp.

◆ setAllowExternalPaths()

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

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

Parameters

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

Definition at line 200 of file package.cpp.

◆ 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

prefix paths the directory prefix to use

Since: 4.6

Definition at line 602 of file package.cpp.

◆ 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

mimeTypes a list of mimeTypes

Definition at line 740 of file package.cpp.

◆ setDefaultPackageRoot()

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

Sets preferred package root.

Definition at line 160 of file package.cpp.

◆ 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

path	package root path

See also: setPath

Definition at line 169 of file package.cpp.

◆ 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

Definition at line 194 of file package.cpp.

◆ 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

key	the entry within the package
mimeTypes	a list of mimeTypes

Definition at line 746 of file package.cpp.

◆ setPath()

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

Sets the path to the root of this package.

Parameters

path	an absolute path, or a relative path to the default package root

Since: 4.3

Definition at line 468 of file package.cpp.

◆ 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

key	the entry within the package
required	true if this entry is required, false if not

Definition at line 727 of file package.cpp.

◆ 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

Definition at line 856 of file package.cpp.

◆ 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

Definition at line 834 of file package.cpp.

The documentation for this class was generated from the following files:

KPackage::Package::Package

Package(PackageStructure *structure=nullptr)

Default constructor.

Definition: package.cpp:35

KPackage::Package::mimeTypes

QStringList mimeTypes(const QByteArray &key) const

Definition: package.cpp:141

i18n

QString i18n(const char *text, const TYPE &arg...)

QList::clear

void clear()

QStringList

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KPackage

KPackage::Package

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ JobError

Constructor & Destructor Documentation

◆ Package() [1/2]

◆ Package() [2/2]

Member Function Documentation

◆ addDirectoryDefinition()

◆ addFileDefinition()

◆ allowExternalPaths()

◆ contentsHash()

◆ contentsPrefixPaths()

◆ cryptographicHash()

◆ defaultPackageRoot()

◆ directories()

◆ entryList()

◆ fallbackPackage()

◆ filePath()

◆ files()

◆ fileUrl()

◆ hasValidStructure()

◆ install()

◆ isRequired()

◆ isValid()

◆ metadata()

◆ mimeTypes()

◆ name()

◆ operator=()

◆ path()

◆ removeDefinition()

◆ requiredDirectories()

◆ requiredFiles()

◆ setAllowExternalPaths()

◆ setContentsPrefixPaths()

◆ setDefaultMimeTypes()

◆ setDefaultPackageRoot()

◆ setFallbackPackage()

◆ setMetadata()

◆ setMimeTypes()

◆ setPath()

◆ setRequired()

◆ uninstall()

◆ update()