plasma/package.h

   1 /******************************************************************************
   2 *   Copyright 2007 by Aaron Seigo <aseigo@kde.org>                        *
   3 *   Copyright 2007 by Riccardo Iaconelli <riccardo@kde.org>               *
   4 *                                                                             *
   5 *   This library is free software; you can redistribute it and/or             *
   6 *   modify it under the terms of the GNU Library General Public               *
   7 *   License as published by the Free Software Foundation; either              *
   8 *   version 2 of the License, or (at your option) any later version.          *
   9 *                                                                             *
  10 *   This library is distributed in the hope that it will be useful,           *
  11 *   but WITHOUT ANY WARRANTY; without even the implied warranty of            *
  12 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU          *
  13 *   Library General Public License for more details.                          *
  14 *                                                                             *
  15 *   You should have received a copy of the GNU Library General Public License *
  16 *   along with this library; see the file COPYING.LIB.  If not, write to      *
  17 *   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,      *
  18 *   Boston, MA 02110-1301, USA.                                               *
  19 *******************************************************************************/
  20
  21 #ifndef PLASMA_PACKAGE_H
  22 #define PLASMA_PACKAGE_H
  23
  24 #include <QtCore/QStringList>
  25
  26 #include <plasma/plasma_export.h>
  27 #include <plasma/packagestructure.h>
  28
  29 namespace Plasma
  30 {
  31
  32 /**
  33  * @class Package plasma/package.h <Plasma/Package>
  34  *
  35  * @short object representing an installed Plasmagik package
  36  **/
  37
  38 class PackageMetadata;
  39 class PackagePrivate;
  40
  41 class PLASMA_EXPORT Package
  42 {
  43     public:
  44         /**
  45          * Default constructor
  46          *
  47          * @arg packageRoot path to the package installation root
  48          * @arg package the name of the package
  49          * @arg structure the package structure describing this package
  50          **/
  51         Package(const QString &packageRoot, const QString &package,
  52                 PackageStructure::Ptr structure);
  53
  54         /**
  55           * Construct a Package object.
  56           *
  57           * @arg packagePath full path to the package directory
  58           * @arg structure the package structure describing this package
  59           */
  60         Package(const QString &packagePath, PackageStructure::Ptr structure);
  61
  62         //TODO for 4.1: be able to load an uninstalled/uncompressed file.
  63
  64         ~Package();
  65
  66         /**
  67          * @return true if all the required components as defined in
  68          * the PackageStructure exist
  69          **/
  70         bool isValid() const;
  71
  72         /**
  73          * Get the path to a given file.
  74          *
  75          * @arg fileType the type of file to look for, as defined in the
  76          *               package structure
  77          * @arg filename the name of the file
  78          * @return path to the file on disk. QString() if not found.
  79          **/
  80         QString filePath(const char *fileType, const QString &filename) const;
  81
  82         /**
  83          * Get the path to a given file.
  84          *
  85          * @arg fileType the type of file to look for, as defined in the
  86          *               package structure. The type must refer to a file
  87          *               in the package structure and not a directory.
  88          * @return path to the file on disk. QString() if not found
  89          **/
  90         QString filePath(const char *fileType) const;
  91
  92         /**
  93          * Get the list of files of a given type.
  94          *
  95          * @arg fileType the type of file to look for, as defined in the
  96          *               package structure.
  97          * @return list of files by name, suitable for passing to filePath
  98          **/
  99         QStringList entryList(const char *fileType) const;
 100
 101         /**
 102           * @return the package metadata object.
 103           */
 104         PackageMetadata metadata() const;
 105
 106         /**
 107          * @return the path to the root of this particular package
 108          */
 109         const QString path() const;
 110
 111         /**
 112          * @return the PackageStructure use in this Package
 113          */
 114         const PackageStructure::Ptr structure() const;
 115
 116         /**
 117          * Returns a list of all installed packages by name
 118          *
 119          * @param packageRoot path to the directory where Plasmagik packages
 120          *                    have been installed to
 121          * @return a list of installed Plasmagik packages
 122          **/
 123         static QStringList listInstalled(const QString &packageRoot);
 124
 125         /**
 126          * Returns a list of all paths of installed packages in the given root
 127          *
 128          * @param packageRoot path to the directory where Plasmagik packages
 129          *                    have been installed to
 130          * @return a list of installed Plasmagik packages by path
 131          **/
 132         static QStringList listInstalledPaths(const QString &packageRoot);
 133
 134         /**
 135          * Installs a package.
 136          *
 137          * @param package path to the Plasmagik package
 138          * @param packageRoot path to the directory where the package should be
 139          *                    installed to
 140          * @param servicePrefix the prefix for the desktop file, so as not to interfere
 141          *                      with unrelated services (eg: "plasma-applet-")
 142          * @return true on successful installation, false otherwise
 143          **/
 144         static bool installPackage(const QString &package,
 145                                    const QString &packageRoot,
 146                                    const QString &servicePrefix);
 147
 148         /**
 149          * Uninstalls a package.
 150          *
 151          * @param package path to the Plasmagik package
 152          * @param packageRoot path to the directory where the package should be
 153          *                    installed to
 154          * @param servicePrefix the prefix for the desktop file, so as not to interfere
 155          *                      with unrelated services (eg: "plasma-applet-")
 156          * @return true on successful uninstallation, false otherwise
 157          **/
 158         static bool uninstallPackage(const QString &package,
 159                                      const QString &packageRoot,
 160                                      const QString &servicePrefix);
 161
 162         /**
 163          * Registers a package described by the given desktop file
 164          *
 165          * @arg the full path to the desktop file (must be KPluginInfo compatible)
 166          * @return true on success, false on failure
 167          */
 168         static bool registerPackage(const PackageMetadata &data, const QString &iconPath);
 169
 170         /**
 171          * Creates a package based on the metadata from the files contained
 172          * in the source directory
 173          *
 174          * @arg metadata description of the package to create
 175          * @arg source path to local directory containing the individual
 176          *             files to be added to the package
 177          * @arg destination path to the package that should be created
 178          * @arg icon path to the package icon
 179          **/
 180         static bool createPackage(const PackageMetadata &metadata,
 181                                   const QString &source,
 182                                   const QString &destination,
 183                                   const QString &icon = QString());
 184
 185     private:
 186         Q_DISABLE_COPY(Package)
 187         PackagePrivate * const d;
 188 };
 189
 190 } // Namespace
 191
 192 #endif
 193