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 | |
30 | namespace Plasma |
31 | { |
32 | |
33 | /** |
34 | * @class Package plasma/package.h <Plasma/Package> |
35 | * |
36 | * @short object representing an installed Plasmagik package |
37 | **/ |
38 | |
39 | class PackageMetadata; |
40 | class PackagePrivate; |
41 | |
42 | class 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 | |
242 | Q_DECLARE_METATYPE(Plasma::Package) |
243 | #endif |
244 | |
245 | |