1 | /* |
2 | SPDX-FileCopyrightText: 2010 Ryan Rix <ry@n.rix.si> |
3 | |
4 | SPDX-License-Identifier: LGPL-2.0-or-later |
5 | */ |
6 | |
7 | #ifndef KPACKAGE_LOADER_H |
8 | #define KPACKAGE_LOADER_H |
9 | |
10 | #include <kpackage/package.h> |
11 | |
12 | #include <kpackage/package_export.h> |
13 | |
14 | namespace KPackage |
15 | { |
16 | class PackageLoaderPrivate; |
17 | |
18 | /** |
19 | * @class PackageLoader kpackage/packageloader.h <KPackage/PackageLoader> |
20 | * |
21 | * This is an abstract base class which defines an interface to which the package |
22 | * loading logic can communicate with a parent application. The plugin loader |
23 | * must be set before any plugins are loaded, otherwise (for safety reasons), the |
24 | * default PackageLoader implementation will be used. The reimplemented version should |
25 | * not do more than simply returning a loaded plugin. It should not init() it, and it should not |
26 | * hang on to it. |
27 | * |
28 | * @author Ryan Rix <ry@n.rix.si> |
29 | **/ |
30 | class KPACKAGE_EXPORT PackageLoader |
31 | { |
32 | public: |
33 | /** |
34 | * Load a Package plugin. |
35 | * |
36 | * @param packageFormat the format of the package to load |
37 | * @param packagePath the package name: the path of the package relative to the |
38 | * packageFormat root path. If not specified it will have to be set manually |
39 | * with Package::setPath() by the caller. |
40 | * |
41 | * @return a Package object matching name, or an invalid package on failure |
42 | **/ |
43 | Package loadPackage(const QString &packageFormat, const QString &packagePath = QString()); |
44 | |
45 | /** |
46 | * List all available packages of a certain type |
47 | * |
48 | * @param packageFormat the format of the packages to list |
49 | * @param packageRoot the root folder where the packages are installed. |
50 | * If not specified the default from the packageformat will be taken. |
51 | * |
52 | * @return metadata for all the matching packages |
53 | */ |
54 | QList<KPluginMetaData> listPackages(const QString &packageFormat, const QString &packageRoot = QString()); |
55 | |
56 | /** |
57 | * @overload |
58 | * @since 6.0 |
59 | */ |
60 | QList<KPluginMetaData> listPackagesMetadata(const QString &packageFormat, const QString &packageRoot = QString()); |
61 | |
62 | /** |
63 | * 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 |
64 | * contained files of the package. |
65 | * |
66 | * @param packageFormat the format of the packages to list |
67 | * @param packageRoot the root folder where the packages are installed. |
68 | * If not specified the default from the packageformat will be taken. |
69 | * |
70 | * @since 6.0 |
71 | */ |
72 | QList<Package> listKPackages(const QString &packageFormat, const QString &packageRoot = QString()); |
73 | |
74 | /** |
75 | * List package of a certain type that match a certain filter function |
76 | * |
77 | * @param packageFormat the format of the packages to list |
78 | * @param packageRoot the root folder where the packages are installed. |
79 | * If not specified the default from the packageformat will be taken. |
80 | * @param filter a filter function that will be called on each package: |
81 | * will return true for the matching ones |
82 | * |
83 | * @return metadata for all the matching packages |
84 | * @since 5.10 |
85 | */ |
86 | QList<KPluginMetaData> findPackages(const QString &packageFormat, |
87 | const QString &packageRoot = QString(), |
88 | std::function<bool(const KPluginMetaData &)> filter = std::function<bool(const KPluginMetaData &)>()); |
89 | |
90 | /** |
91 | * Loads a PackageStructure for a given format. The structure can then be used as |
92 | * paramenter for a Package instance constructor |
93 | * |
94 | * @note The returned pointer is managed by KPackage, and should never be deleted |
95 | * |
96 | * @param packageFormat the package format, such as "KPackage/GenericQML" |
97 | * @return the structure instance (ownership retained by KPackage) |
98 | */ |
99 | KPackage::PackageStructure *loadPackageStructure(const QString &packageFormat); |
100 | |
101 | /** |
102 | * Adds a new known package structure that can be used by the functions to load packages such |
103 | * as loadPackage, findPackages etc |
104 | * @param packageFormat the package format, such as "KPackage/GenericQML" |
105 | * @param structure the package structure we want to be able to load packages from |
106 | * @since 5.10 |
107 | */ |
108 | void addKnownPackageStructure(const QString &packageFormat, KPackage::PackageStructure *structure); |
109 | |
110 | /** |
111 | * Return the active plugin loader |
112 | **/ |
113 | static PackageLoader *self(); |
114 | |
115 | protected: |
116 | PackageLoader(); |
117 | virtual ~PackageLoader(); |
118 | |
119 | private: |
120 | friend class Package; |
121 | friend class PackageJob; |
122 | KPACKAGE_NO_EXPORT static void invalidateCache(); |
123 | |
124 | PackageLoaderPrivate *const d; |
125 | Q_DISABLE_COPY(PackageLoader) |
126 | }; |
127 | |
128 | } |
129 | |
130 | Q_DECLARE_METATYPE(KPackage::PackageLoader *) |
131 | |
132 | #endif |
133 | |