inc/FAppPkgPackageManager.h

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