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.h>
27#include <plasma/packagestructure.h>
28#include <plasma/plasma_export.h>
29
30namespace Plasma
31{
32
33/**
34 * @class Package plasma/package.h <Plasma/Package>
35 *
36 * @short object representing an installed Plasmagik package
37 **/
38
39class PackageMetadata;
40class PackagePrivate;
41
42class PLASMA_EXPORT Package
43{
44 public:
45 /**
46 * Default constructor that creates an invalid Package
47 * @since 4.6
48 */
49 explicit Package();
50
51 /**
52 * Construct a Package object
53 *
54 * @param packageRoot path to the package installation root
55 * @param package the name of the package
56 * @param structure the package structure describing this package
57 **/
58 Package(const QString &packageRoot, const QString &package,
59 PackageStructure::Ptr structure);
60
61 /**
62 * Construct a Package object.
63 *
64 * @param packagePath full path to the package directory
65 * @param structure the package structure describing this package
66 */
67 Package(const QString &packagePath, PackageStructure::Ptr structure);
68
69 /**
70 * Copy constructore
71 * @since 4.6
72 */
73 Package(const Package &other);
74
75 ~Package();
76
77 /**
78 * Assignment operator
79 * @since 4.6
80 */
81 Package &operator=(const Package &rhs);
82
83 /**
84 * @return true if all the required components as defined in
85 * the PackageStructure exist
86 **/
87 bool isValid() const;
88
89 /**
90 * Get the path to a given file.
91 *
92 * @param fileType the type of file to look for, as defined in the
93 * package structure
94 * @param filename the name of the file
95 * @return path to the file on disk. QString() if not found.
96 **/
97 QString filePath(const char *fileType, const QString &filename) const;
98
99 /**
100 * Get the path to a given file.
101 *
102 * @param fileType the type of file to look for, as defined in the
103 * package structure. The type must refer to a file
104 * in the package structure and not a directory.
105 * @return path to the file on disk. QString() if not found
106 **/
107 QString filePath(const char *fileType) const;
108
109 /**
110 * Get the list of files of a given type.
111 *
112 * @param fileType the type of file to look for, as defined in the
113 * package structure.
114 * @return list of files by name, suitable for passing to filePath
115 **/
116 QStringList entryList(const char *fileType) const;
117
118 /**
119 * @return the package metadata object.
120 */
121 PackageMetadata metadata() const;
122
123 /**
124 * Sets the path to the root of this package
125 * @param path and absolute path
126 * @since 4.3
127 */
128 void setPath(const QString &path);
129
130 /**
131 * Publish this package on the network.
132 * @param methods the ways to announce this package on the network.
133 */
134 void publish(AnnouncementMethods methods, const QString &name);
135
136 /**
137 * Remove this package from the network.
138 */
139 void unpublish(const QString &name = QString());
140
141 /**
142 * @returns whether or not this service is currently published on the network.
143 */
144 bool isPublished() const;
145
146 /**
147 * @return the path to the root of this particular package
148 */
149 const QString path() const;
150
151 /**
152 * @return the PackageStructure use in this Package
153 */
154 const PackageStructure::Ptr structure() const;
155
156 /**
157 * @return a SHA1 hash digest of the contents of the package in hexadecimal form
158 * @since 4.4
159 */
160 QString contentsHash() const;
161
162 /**
163 * Returns a list of all installed packages by name
164 *
165 * @param packageRoot path to the directory where Plasmagik packages
166 * have been installed to
167 * @return a list of installed Plasmagik packages
168 **/
169 static QStringList listInstalled(const QString &packageRoot);
170
171 /**
172 * Returns a list of all paths of installed packages in the given root
173 *
174 * @param packageRoot path to the directory where Plasmagik packages
175 * have been installed to
176 * @return a list of installed Plasmagik packages by path
177 **/
178 static QStringList listInstalledPaths(const QString &packageRoot);
179
180 /**
181 * Installs a package.
182 *
183 * @param package path to the Plasmagik package
184 * @param packageRoot path to the directory where the package should be
185 * installed to
186 * @param servicePrefix the prefix for the desktop file, so as not to interfere
187 * with unrelated services (eg: "plasma-applet-"). If no prefix
188 * is set (e.g. a QString() is passed in), then the package will NOT
189 * be registered as a service
190 * @return true on successful installation, false otherwise
191 **/
192 static bool installPackage(const QString &package,
193 const QString &packageRoot,
194 const QString &servicePrefix);
195
196 /**
197 * Uninstalls a package.
198 *
199 * @param package path to the Plasmagik package
200 * @param packageRoot path to the directory where the package should be
201 * installed to
202 * @param servicePrefix the prefix for the desktop file, so as not to interfere
203 * with unrelated services (eg: "plasma-applet-")
204 * @return true on successful uninstallation, false otherwise
205 **/
206 static bool uninstallPackage(const QString &package,
207 const QString &packageRoot,
208 const QString &servicePrefix);
209
210 /**
211 * Registers a package described by the given desktop file
212 *
213 * @param the full path to the desktop file (must be KPluginInfo compatible)
214 * @return true on success, false on failure
215 */
216 static bool registerPackage(const PackageMetadata &data, const QString &iconPath);
217
218 /**
219 * Creates a package based on the metadata from the files contained
220 * in the source directory
221 *
222 * @param metadata description of the package to create
223 * @param source path to local directory containing the individual
224 * files to be added to the package
225 * @param destination path to the package that should be created
226 * @param icon path to the package icon
227 **/
228 static bool createPackage(const PackageMetadata &metadata,
229 const QString &source,
230 const QString &destination,
231 const QString &icon = QString());
232
233 private:
234 PackagePrivate * const d;
235
236 friend class Applet;
237 friend class AppletPrivate;
238};
239
240} // Namespace
241
242Q_DECLARE_METATYPE(Plasma::Package)
243#endif
244
245