Merge "Update PowerManager Implementation" into tizen_2.1
[platform/framework/native/appfw.git] / inc / FAppPkgPackageManager.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17
18 /**
19  * @file        FAppPkgPackageManager.h
20  * @brief       This is the header file for the %PackageManager class.
21  *
22  * This header file contains the declarations of the %PackageManager class.
23  */
24
25 #ifndef _FAPP_PKG_PACKAGE_MANAGER_H_
26 #define _FAPP_PKG_PACKAGE_MANAGER_H_
27
28 #include <FBase.h>
29 #include <FAppTypes.h>
30
31 namespace Tizen { namespace App { namespace Package
32 {
33
34 class PackageInfo;
35 class PackageAppInfo;
36 class IPackageInstallationEventListener;
37 class IPackageInstallationResponseListener;
38 class IPackageUninstallationResponseListener;
39
40 /**
41  * @enum PackageType
42  *
43  * Defines the package types.
44   *
45  * @since       2.0
46  */
47 enum PackageType
48 {
49         PACKAGE_TYPE_TPK,                       /**< TIZEN Native package */
50         PACKAGE_TYPE_WGT,                       /**< TIZEN %Web package */
51         PACKAGE_TYPE_RPM,                       /**< TIZEN Core package */
52 };
53
54 /**
55  * @class               PackageManager
56  * @brief               This class gets the information of packages and manages package installation or uninstallation.
57  *
58  * @since       2.0
59  *
60  * @final               This class is not intended for extension.
61  *
62  * The %PackageManager class provides methods to install or uninstall the packages, retrieves the information of the packages that are installed on the device.
63  *
64  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/package_namespace.htm">Package Management</a>.
65  *
66  */
67 class _OSP_EXPORT_ PackageManager
68         : public Tizen::Base::Object
69 {
70 public:
71         /**
72          * Gets the package ID from the application ID.
73          *
74          * @since       2.0
75          *
76          * @return              The package ID, @n
77          *                              else @c packageId.IsEmtpy() == true is returned if an error occurs
78          * @param[in]   appId                           The application ID
79          * @exception   E_SUCCESS                       The method is successful.
80          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
81          * @remarks             The specific error code can be accessed using the GetLastResult() method.
82          */
83         static PackageId GetPackageIdByAppId(const AppId& appId);
84
85         /**
86          * Adds a package installation event listener.
87          *
88          * @since       2.0
89          * @privlevel   public
90          * @privilege   %http://tizen.org/privilege/packageinfo
91          *
92          * @return              An error code
93          * @param[in]   listener                        The package installation event listener
94          * @exception   E_SUCCESS                       The method is successful.
95          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
96          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
97          */
98         result AddPackageInstallationEventListener(IPackageInstallationEventListener& listener);
99
100         /**
101          * Removes a package installation event listener.
102          *
103          * @since       2.0
104          * @privlevel   public
105          * @privilege   %http://tizen.org/privilege/packageinfo
106          *
107          * @return              An error code
108          * @param[in]   listener                        The package installation event listener
109          * @exception   E_SUCCESS                       The method is successful.
110          * @exception   E_OBJ_NOT_FOUND         The listener is not added or is already removed.
111          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
112          */
113         result RemovePackageInstallationEventListener(IPackageInstallationEventListener& listener);
114
115         /**
116          * Gets a package information with the specific package ID.
117          *
118          * @since       2.0
119          * @privlevel   public
120          * @privilege   %http://tizen.org/privilege/packageinfo
121          *
122          * @return              A pointer to PackageInfo
123          * @param[in]   packageId                               The package ID
124          * @exception   E_SUCCESS                       The method is successful.
125          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
126          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
127          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
128          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
129          * @remarks             The specific error code can be accessed using the GetLastResult() method.
130          */
131         PackageInfo* GetPackageInfoN(const PackageId& packageId) const;
132
133         /**
134          * Gets the application information with the specific application ID.
135          *
136          * @since       2.0
137          * @privlevel   public
138          * @privilege   %http://tizen.org/privilege/packageinfo
139          *
140          * @return              A pointer to PackageAppInfo
141          * @param[in]   appId                           The application ID
142          * @exception   E_SUCCESS                       The method is successful.
143          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
144          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
145          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
146          * @remarks             The specific error code can be accessed using the GetLastResult() method.
147          */
148         PackageAppInfo* GetPackageAppInfoN(const AppId& appId) const;
149
150         /**
151          * Gets the package information list.
152          *
153          * @since       2.0
154          * @privlevel   public
155          * @privilege   %http://tizen.org/privilege/packageinfo
156          *
157          * @return              A pointer to the list of the PackageInfo instances, @n
158          *                              else @c null if it fails
159          * @exception   E_SUCCESS                       The method is successful.
160          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
161          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
162          * @remarks             The specific error code can be accessed using the GetLastResult() method.
163          */
164         Tizen::Base::Collection::IList* GetPackageInfoListN(void) const;
165
166         /**
167          * Checks whether a package is installed.
168          *
169          * @since       2.0
170          * @privlevel   public
171          * @privilege   %http://tizen.org/privilege/packageinfo
172          *
173          * @return      @c true if a package is installed, @n
174          *                      else @c false
175          * @param[in]   packageId                               The package ID
176          * @exception   E_SUCCESS                       The method is successful.
177          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
178          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
179          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
180          * @remarks             The specific error code can be accessed using the GetLastResult() method.
181          */
182         bool IsPackageInstalled(const PackageId& packageId) const;
183
184         /**
185          * Installs a package. @n
186          * The %InstallPackage() method operates asynchronously, that is, it ends immediately without an installation response. The application is notified when the installation is completed, so the response is available through the IPackageInstallationResponseListener::OnPackageInstallationCompleted() method, if this method returns @c E_SUCCESS.
187          *
188          * @since       2.0
189          * @privlevel   platform
190          * @privilege   %http://tizen.org/privilege/packagemanager.install
191          *
192          * @return              An error code
193          * @param[in]   packageId                       The package ID
194          * @param[in]   packagePath                     The package path
195          * @param[in]   pListener                       The response listener
196          * @exception   E_SUCCESS                       The method is successful.
197          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
198          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
199          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
200          * @remarks             A listener instance ownership is transferred to the platform. After notifying result, the listener instance is removed automatically. A reuse of the listener instance is not allowed.
201          * @see                 IPackageInstallationResponseListener
202          */
203         result InstallPackage(const PackageId& packageId, const Tizen::Base::String& packagePath, IPackageInstallationResponseListener* pListener);
204
205         /**
206          * Uninstalls a package with the specified package ID. @n
207          * The %UninstallPackage() method operates asynchronously, that is, it ends immediately without an uninstallation response. The application is notified when the uninstallation is completed, so the response is available through the IPackageUninstallationResponseListener::OnPackageUninstallationCompleted() method, if this method returns @c true.
208          *
209          * @since       2.0
210          * @privlevel   platform
211          * @privilege   %http://tizen.org/privilege/packagemanager.install
212          *
213          * @return              An error code
214          * @param[in]   packageId                               The package ID
215          * @param[in]   pListener                               The response listener
216          * @exception   E_SUCCESS                               The method is successful.
217          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
218          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
219          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
220          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
221          * @remarks             A listener instance ownership is transferred to the platform. After notifying result, the listener instance is removed automatically. A reuse of the listener instance is not allowed.
222          * @see                 IPackageUninstallationResponseListener
223          */
224         result UninstallPackage(const PackageId& packageId, IPackageUninstallationResponseListener* pListener);
225
226         /**
227          *  Moves a package with the specified package ID to an external storage.
228          *
229          * @since       2.0
230          * @privlevel   platform
231          * @privilege   %http://tizen.org/privilege/packagesetting
232          *
233          * @return              An error code
234          * @param[in]   packageId                               The package ID
235          * @exception   E_SUCCESS                               The method is successful.
236          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
237          * @exception   E_INVALID_OPERATION             The package is already installed in an external storage.
238          * @exception   E_STORAGE_FULL                  The storage is full.
239          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
240          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
241          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
242          */
243         result MoveToExternalStorage(const PackageId& packageId);
244
245         /**
246          * Moves a package with the specified package ID to an internal storage.
247          *
248          * @since       2.0
249          * @privlevel   platform
250          * @privilege   %http://tizen.org/privilege/packagesetting
251          *
252          * @return              An error code
253          * @param[in]   packageId                               The package ID
254          * @exception   E_SUCCESS                               The method is successful.
255          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
256          * @exception   E_INVALID_OPERATION             The package is already installed in an internal storage.
257          * @exception   E_STORAGE_FULL                  The storage is full.
258          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
259          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
260          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
261          */
262         result MoveToInternalStorage(const PackageId& packageId);
263
264         /**
265         * Gets a package information from the specific file. The supported file extensions are tpk and wgt.
266         *
267         * @since         2.1
268         * @privlevel     platform
269         * @privilege     %http://tizen.org/privilege/packagemanager.info
270         *
271         * @return        A pointer to the %PackageInfo instance, @n
272         *               else @c null if it fails
273         * @param[in]    filePath                           The package file path
274         * @exception    E_SUCCESS                          The method is successful.
275         * @exception    E_INVALID_ARG                      A specified input parameter is invalid.
276         * @exception    E_FILE_NOT_FOUND                   The specified file cannot be found or accessed.
277         * @exception    E_UNSUPPORTED_FORMAT               The specified format is invalid or not supported.
278         * @exception    E_PARSING_FAILED                   The method has failed to parse the package file or xml file(s) inside the package.
279         * @exception    E_PRIVILEGE_DENIED                 The application does not have the privilege to call this method.
280         * @remarks      The specific error code can be accessed using the GetLastResult() method.
281         */
282         PackageInfo* GetPackageInfoFromFileN(const Tizen::Base::String& filePath) const;
283
284         /**
285         * Gets the package information list with the package filter.
286         *
287         * @since         2.1
288         * @privlevel     public
289         * @privilege     %http://tizen.org/privilege/package.info
290         *
291         * @return        A pointer to the list of the %PackageInfo instances, @n
292         *                else @c null if it fails
293         * @param[in]     packageFilterMap         The predefined key(Tizen::Base::String)-value(Tizen::Base::Boolean) pairs for the package filter @n
294         * For more information on the predefined key-value pairs for package filter,
295         *       see <a href="../org.tizen.native.appprogramming/html/guide/app/packagefilter.htm">the predefined key-value pairs for package filter</a>.
296         * @exception    E_SUCCESS                            The method is successful.
297         * @exception    E_INVALID_ARG                        A specified input parameter is invalid.
298         * @exception    E_SYSTEM                             The method cannot proceed due to a severe system error.
299         * @exception    E_PRIVILEGE_DENIED                   The application does not have the privilege to call this method.
300         * @remarks      The specific error code can be accessed using the GetLastResult() method.
301         */
302         Tizen::Base::Collection::IList* GetPackageInfoListN(const Tizen::Base::Collection::IMap& packageFilterMap) const;
303
304         /**
305         * Gets the application information list with the package app filter.
306         *
307         * @since         2.1
308         * @privlevel     public
309         * @privilege     %http://tizen.org/privilege/package.info
310         *
311         * @return        A pointer to the list of the %PackageAppInfo instances, @n
312         *                else @c null if it fails
313         * @param[in]     packageAppFilterMap      The predefined key(Tizen::Base::String)-value(Tizen::Base::String or Tizen::Base::Boolean) pairs for the package app filter @n
314         * For more information on the predefined key-value pairs for package app filter,
315         *       see <a href="../org.tizen.native.appprogramming/html/guide/app/packageappfilter.htm">the predefined key-value pairs for package app filter</a>.
316         * @exception    E_SUCCESS                            The method is successful.
317         * @exception    E_INVALID_ARG                        A specified input parameter is invalid.
318         * @exception    E_SYSTEM                             The method cannot proceed due to a severe system error.
319         * @exception    E_PRIVILEGE_DENIED                   The application does not have the privilege to call this method.
320         * @remarks      The specific error code can be accessed using the GetLastResult() method.
321         */
322         Tizen::Base::Collection::IList* GetPackageAppInfoListN(const Tizen::Base::Collection::IMap& packageAppFilterMap) const;
323
324         /**
325         * Gets the application information list with the package filter and package app filter.
326         *
327         * @since         2.1
328         * @privlevel     public
329         * @privilege     %http://tizen.org/privilege/package.info
330         *
331         * @return        A pointer to the list of the %PackageAppInfo instances, @n
332         *                              else @c null if it fails
333         * @param[in] packageFilterMap        The predefined key(Tizen::Base::String)-value(Tizen::Base::Boolean) pairs for the package filter @n
334         * @param[in] packageAppFilterMap     The predefined and user defined key(Tizen::Base::String)-value(Tizen::Base::String or Tizen::Base::Boolean) pairs for the package app filter @n
335         *                                    The user defined key-value pairs can be added in <Metadata> of manifest.xml.
336         *
337         * For more information on the predefined key-value pairs for package filter,
338         *              see <a href="../org.tizen.native.appprogramming/html/guide/app/packagefilter.htm">the predefined key-value pairs for package filter</a>.
339         * For more information on the predefined key-value pairs for package app filter,
340         *              see <a href="../org.tizen.native.appprogramming/html/guide/app/packageappfilter.htm">the predefined key-value pairs for package app filter</a>.
341         *
342         * @exception    E_SUCCESS                            The method is successful.
343         * @exception    E_INVALID_ARG                        A specified input parameter is invalid.
344         * @exception    E_SYSTEM                             The method cannot proceed due to a severe system error.
345         * @exception    E_PRIVILEGE_DENIED                   The application does not have the privilege to call this method.
346         * @remarks      The specific error code can be accessed using the GetLastResult() method.
347         */
348         Tizen::Base::Collection::IList* GetPackageAppInfoListN(const Tizen::Base::Collection::IMap& packageFilterMap, const Tizen::Base::Collection::IMap& packageAppFilterMap) const;
349
350         /**
351          * Gets the package manager instance.
352          *
353          * @since       2.0
354          *
355          * @return              A pointer to the %PackageManager instance, @n
356          *                              else @c null
357          * @remarks             The specific error code can be accessed using the GetLastResult() method.
358          */
359         static PackageManager* GetInstance(void);
360
361 private:
362         /**
363          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
364          *
365          * @since       2.0
366          */
367         PackageManager(void);
368
369         /**
370          * This destructor is intentionally declared as private to implement the %Singleton semantic.
371          *
372          * @since       2.0
373          */
374         virtual ~PackageManager(void);
375
376         /**
377          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
378          *
379          * @since       2.0
380          */
381         PackageManager(const PackageManager& rhs);
382
383         /**
384          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
385          *
386          * @since       2.0
387          */
388         PackageManager& operator =(const PackageManager& rhs);
389
390 private:
391         class _PackageManagerImpl* __pPackageManagerImpl;
392         friend class _PackageManagerImpl;
393
394 }; // PackageManager
395
396 } } } // Tizen::App::Package
397
398 #endif // _FAPP_PKG_PACKAGE_MANAGER_H_