File indexing completed on 2024-07-14 14:35:39

0001 /*
0002     SPDX-FileCopyrightText: 2011 Aaron Seigo <aseigo@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef KPACKAGE_PACKAGESTRUCTURE_H
0008 #define KPACKAGE_PACKAGESTRUCTURE_H
0009 
0010 #include <QStringList>
0011 
0012 #include <KPluginFactory>
0013 
0014 #include <kpackage/package.h>
0015 #include <kpackage/package_export.h>
0016 
0017 namespace KPackage
0018 {
0019 class PackageStructurePrivate;
0020 
0021 /**
0022  * @class PackageStructure kpackage/packagestructure.h <KPackage/PackageStructure>
0023  *
0024  * This class is used to define the filesystem structure of a package type.
0025  * A PackageStructure is implemented as a dynamically loaded plugin, in the reimplementation
0026  * of initPackage the allowed fines and directories in the package are set into the package,
0027  * for instance:
0028  *
0029  * @code
0030  * package->addFileDefinition("mainscript", QStringLiteral("ui/main.qml"), i18n("Main Script File"));
0031  * package->setDefaultPackageRoot(QStringLiteral("plasma/wallpapers/"));
0032  * package->addDirectoryDefinition("images", QStringLiteral("images"), i18n("Images"));
0033  * package->addDirectoryDefinition("theme", QStringLiteral("theme"), i18n("Themed Images"));
0034  * QStringList mimetypes;
0035  * mimetypes << QStringLiteral("image/svg+xml") << QStringLiteral("image/png") << QStringLiteral("image/jpeg");
0036  * package->setMimeTypes("images", mimetypes);
0037  * @endcode
0038  *
0039  * @author Aaron Seigo
0040  */
0041 class KPACKAGE_EXPORT PackageStructure : public QObject
0042 {
0043     Q_OBJECT
0044 
0045 public:
0046     explicit PackageStructure(QObject *parent = nullptr, const QVariantList &args = QVariantList());
0047 
0048     ~PackageStructure() override;
0049 
0050     /**
0051      * Called when a the PackageStructure should initialize a Package with the initial
0052      * structure. This allows setting paths before setPath is called.
0053      *
0054      * Note: one special value is "metadata" which can be set to the location of KPluginMetaData
0055      * compatible .desktop file within the package. If not defined, it is assumed that this file
0056      * exists under the top level directory of the package.
0057      *
0058      * @param package the Package to set up. The object is empty of all definition when
0059      *      first passed in.
0060      */
0061     virtual void initPackage(Package *package);
0062 
0063     /**
0064      * Called whenever the path changes so that subclasses may take
0065      * package specific actions.
0066      */
0067     virtual void pathChanged(Package *package);
0068 
0069     /**
0070      * Installs a package matching this package structure. By default installs a
0071      * native KPackage::Package.
0072      *
0073      * @param package the instance of Package that is being used for the install; useful for
0074      * accessing file paths
0075      * @param archivePath path to the package archive file
0076      * @param packageRoot path to the directory where the package should be
0077      *                    installed to
0078      * @return KJob* to track the installation status
0079      **/
0080     virtual KJob *install(Package *package, const QString &archivePath, const QString &packageRoot);
0081 
0082     /**
0083      * Updates a package matching this package structure. By default installs a
0084      * native KPackage::Package. If an older version is already installed,
0085      * it removes the old one. If the installed one is newer,
0086      * an error will occur.
0087      *
0088      * @param package the instance of Package that is being used for the install; useful for
0089      * accessing file paths
0090      * @param archivePath path to the package archive file
0091      * @param packageRoot path to the directory where the package should be
0092      *                    installed to
0093      * @return KJob* to track the installation status
0094      * @since 5.17
0095      **/
0096     virtual KJob *update(Package *package, const QString &archivePath, const QString &packageRoot);
0097 
0098     /**
0099      * Uninstalls a package matching this package structure.
0100      *
0101      * @param package the instance of Package that is being used for the install; useful for
0102      * accessing file paths
0103      * @param packageName the name of the package to remove
0104      * @param packageRoot path to the directory where the package should be installed to
0105      * @return KJob* to track the installation status
0106      */
0107     virtual KJob *uninstall(Package *package, const QString &packageRoot);
0108 
0109 private:
0110     PackageStructurePrivate *d;
0111 };
0112 
0113 } // KPackage namespace
0114 
0115 /**
0116  * Register a Package class when it is contained in a loadable module
0117  */
0118 
0119 #define K_EXPORT_KPACKAGE_PACKAGE_WITH_JSON(classname, jsonFile) K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin<classname>();)
0120 
0121 #endif