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/package.info
  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/package.info
 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/package.info
 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/package.info
 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/package.info
 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/package.info
 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/package.setting
 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/package.setting
 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_