File indexing completed on 2024-02-25 04:01:48

0001 /*
0002     SPDX-FileCopyrightText: 2010 Ryan Rix <ry@n.rix.si>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef KPACKAGE_LOADER_H
0008 #define KPACKAGE_LOADER_H
0009 
0010 #include <kpackage/package.h>
0011 
0012 #include <kpackage/package_export.h>
0013 
0014 namespace KPackage
0015 {
0016 class PackageLoaderPrivate;
0017 
0018 /**
0019  * @class PackageLoader kpackage/packageloader.h <KPackage/PackageLoader>
0020  *
0021  * This is an abstract base class which defines an interface to which the package
0022  * loading logic can communicate with a parent application. The plugin loader
0023  * must be set before any plugins are loaded, otherwise (for safety reasons), the
0024  * default PackageLoader implementation will be used. The reimplemented version should
0025  * not do more than simply returning a loaded plugin. It should not init() it, and it should not
0026  * hang on to it.
0027  *
0028  * @author Ryan Rix <ry@n.rix.si>
0029  **/
0030 class KPACKAGE_EXPORT PackageLoader
0031 {
0032 public:
0033     /**
0034      * Load a Package plugin.
0035      *
0036      * @param packageFormat the format of the package to load
0037      * @param packagePath the package name: the path of the package relative to the
0038      *        packageFormat root path. If not specified it will have to be set manually
0039      *        with Package::setPath() by the caller.
0040      *
0041      * @return a Package object matching name, or an invalid package on failure
0042      **/
0043     Package loadPackage(const QString &packageFormat, const QString &packagePath = QString());
0044 
0045     /**
0046      * List all available packages of a certain type
0047      *
0048      * @param packageFormat the format of the packages to list
0049      * @param packageRoot the root folder where the packages are installed.
0050      *          If not specified the default from the packageformat will be taken.
0051      *
0052      * @return metadata for all the matching packages
0053      */
0054     QList<KPluginMetaData> listPackages(const QString &packageFormat, const QString &packageRoot = QString());
0055 
0056     /**
0057      * @overload
0058      * @since 6.0
0059      */
0060     QList<KPluginMetaData> listPackagesMetadata(const QString &packageFormat, const QString &packageRoot = QString());
0061 
0062     /**
0063      * List all available packages of a certain type. This should be used in case the package structure modifies the metadata or you need to access the
0064      * contained files of the package.
0065      *
0066      * @param packageFormat the format of the packages to list
0067      * @param packageRoot the root folder where the packages are installed.
0068      *          If not specified the default from the packageformat will be taken.
0069      *
0070      * @since 6.0
0071      */
0072     QList<Package> listKPackages(const QString &packageFormat, const QString &packageRoot = QString());
0073 
0074     /**
0075      * List package of a certain type that match a certain filter function
0076      *
0077      * @param packageFormat the format of the packages to list
0078      * @param packageRoot the root folder where the packages are installed.
0079      *          If not specified the default from the packageformat will be taken.
0080      * @param filter a filter function that will be called on each package:
0081      *          will return true for the matching ones
0082      *
0083      * @return metadata for all the matching packages
0084      * @since 5.10
0085      */
0086     QList<KPluginMetaData> findPackages(const QString &packageFormat,
0087                                         const QString &packageRoot = QString(),
0088                                         std::function<bool(const KPluginMetaData &)> filter = std::function<bool(const KPluginMetaData &)>());
0089 
0090     /**
0091      * Loads a PackageStructure for a given format. The structure can then be used as
0092      * paramenter for a Package instance constructor
0093      *
0094      * @note The returned pointer is managed by KPackage, and should never be deleted
0095      *
0096      * @param packageFormat the package format, such as "KPackage/GenericQML"
0097      * @return the structure instance (ownership retained by KPackage)
0098      */
0099     KPackage::PackageStructure *loadPackageStructure(const QString &packageFormat);
0100 
0101     /**
0102      * Adds a new known package structure that can be used by the functions to load packages such
0103      * as loadPackage, findPackages etc
0104      * @param packageFormat the package format, such as "KPackage/GenericQML"
0105      * @param structure the package structure we want to be able to load packages from
0106      * @since 5.10
0107      */
0108     void addKnownPackageStructure(const QString &packageFormat, KPackage::PackageStructure *structure);
0109 
0110     /**
0111      * Return the active plugin loader
0112      **/
0113     static PackageLoader *self();
0114 
0115 protected:
0116     PackageLoader();
0117     virtual ~PackageLoader();
0118 
0119 private:
0120     friend class Package;
0121     friend class PackageJob;
0122     KPACKAGE_NO_EXPORT static void invalidateCache();
0123 
0124     PackageLoaderPrivate *const d;
0125     Q_DISABLE_COPY(PackageLoader)
0126 };
0127 
0128 }
0129 
0130 Q_DECLARE_METATYPE(KPackage::PackageLoader *)
0131 
0132 #endif