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          */
 207         result InstallPackage(const PackageId& packageId, const Tizen::Base::String& packagePath, IPackageInstallationResponseListener* pListener);
 208
 209         /**
 210          * Uninstalls a package with the specified package ID. @n
 211          * 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.
 212          *
 213          * @since       2.0
 214          * @privlevel   platform
 215          * @privilege   %http://tizen.org/privilege/packagemanager.install
 216          *
 217          * @return              An error code
 218          * @param[in]   packageId                               The package ID
 219          * @param[in]   pListener                               The response listener
 220          * @exception   E_SUCCESS                               The method is successful.
 221          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 222          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 223          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
 224          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 225          * @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.
 226          */
 227         result UninstallPackage(const PackageId& packageId, IPackageUninstallationResponseListener* pListener);
 228
 229         /**
 230          *  Moves a package with the specified package ID to an external storage.
 231          *
 232          * @since       2.0
 233          * @privlevel   platform
 234          * @privilege   %http://tizen.org/privilege/packagemanager.setting @n
 235          *                                       (%http://tizen.org/privilege/packagesetting is deprecated.)
 236          *
 237          * @return              An error code
 238          * @param[in]   packageId                               The package ID
 239          * @exception   E_SUCCESS                               The method is successful.
 240          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 241          * @exception   E_INVALID_OPERATION             The package is already installed in an external storage.
 242          * @exception   E_STORAGE_FULL                  The storage is full.
 243          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
 244          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 245          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 246          */
 247         result MoveToExternalStorage(const PackageId& packageId);
 248
 249         /**
 250          * Moves a package with the specified package ID to an internal storage.
 251          *
 252          * @since       2.0
 253          * @privlevel   platform
 254          * @privilege   %http://tizen.org/privilege/packagemanager.setting @n
 255          *                                       (%http://tizen.org/privilege/packagesetting is deprecated.)
 256          *
 257          * @return              An error code
 258          * @param[in]   packageId                               The package ID
 259          * @exception   E_SUCCESS                               The method is successful.
 260          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 261          * @exception   E_INVALID_OPERATION             The package is already installed in an internal storage.
 262          * @exception   E_STORAGE_FULL                  The storage is full.
 263          * @exception   E_PKG_NOT_INSTALLED             The package is not installed.
 264          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 265          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 266          */
 267         result MoveToInternalStorage(const PackageId& packageId);
 268
 269         /**
 270         * Gets a package information from a specific file. @n The supported file extensions are tpk and wgt.
 271         *
 272         * @since         2.1
 273         * @privlevel     platform
 274         * @privilege     %http://tizen.org/privilege/packagemanager.info
 275         *
 276         * @return        A pointer to the PackageInfo instance, @n
 277         *               else @c null if it fails
 278         * @param[in]    filePath                           The package file path
 279         * @exception    E_SUCCESS                          The method is successful.
 280         * @exception    E_INVALID_ARG                      The specified input parameter is invalid.
 281         * @exception    E_FILE_NOT_FOUND                   The specified file cannot be found or accessed.
 282         * @exception    E_UNSUPPORTED_FORMAT               The specified format is invalid or not supported.
 283         * @exception    E_PARSING_FAILED                   The method has failed to parse the package file or xml file(s) inside the package.
 284         * @exception    E_PRIVILEGE_DENIED                 The application does not have the privilege to call this method.
 285         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 286         */
 287         PackageInfo* GetPackageInfoFromFileN(const Tizen::Base::String& filePath) const;
 288
 289         /**
 290         * Gets the package information list with the package filter.
 291         *
 292         * @since         2.1
 293         * @privlevel     public
 294         * @privilege     %http://tizen.org/privilege/package.info
 295         *
 296         * @return        A pointer to the list of the PackageInfo instances, @n
 297         *                else @c null if it fails
 298         * @param[in]     packageFilterMap         The predefined key(Tizen::Base::String)-value(Tizen::Base::Boolean) pairs for the package filter @n
 299         * For more information on the predefined key-value pairs for package filter,
 300         *       see <a href="../org.tizen.native.appprogramming/html/guide/app/package_app_filter.htm">the predefined key-value pairs for package filter</a>.
 301         * @exception    E_SUCCESS                            The method is successful.
 302         * @exception    E_INVALID_ARG                        The specified input parameter is invalid.
 303         * @exception    E_SYSTEM                             The method cannot proceed due to a severe system error.
 304         * @exception    E_PRIVILEGE_DENIED                   The application does not have the privilege to call this method.
 305         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 306         */
 307         Tizen::Base::Collection::IList* GetPackageInfoListN(const Tizen::Base::Collection::IMap& packageFilterMap) const;
 308
 309         /**
 310         * Gets the application information list with the package app filter.
 311         *
 312         * @since         2.1
 313         * @privlevel     public
 314         * @privilege     %http://tizen.org/privilege/package.info
 315         *
 316         * @return        A pointer to the list of the PackageAppInfo instances, @n
 317         *                else @c null if it fails
 318         * @param[in]     packageAppFilterMap      The predefined key(Tizen::Base::String)-value(Tizen::Base::String or Tizen::Base::Boolean) pairs for the package app filter @n
 319         * For more information, see <a href="../org.tizen.native.appprogramming/html/guide/app/package_app_filter.htm">
 320         * the predefined key-value pairs for package app filter</a>.
 321         * @exception    E_SUCCESS                            The method is successful.
 322         * @exception    E_INVALID_ARG                        The specified input parameter is invalid.
 323         * @exception    E_SYSTEM                             The method cannot proceed due to a severe system error.
 324         * @exception    E_PRIVILEGE_DENIED                   The application does not have the privilege to call this method.
 325         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 326         */
 327         Tizen::Base::Collection::IList* GetPackageAppInfoListN(const Tizen::Base::Collection::IMap& packageAppFilterMap) const;
 328
 329         /**
 330         * Gets the application information list with the package filter and package app filter.
 331         *
 332         * @since         2.1
 333         * @privlevel     public
 334         * @privilege     %http://tizen.org/privilege/package.info
 335         *
 336         * @return        A pointer to the list of the PackageAppInfo instances, @n
 337         *                              else @c null if it fails
 338         * @param[in] packageFilterMap        The predefined key(Tizen::Base::String)-value(Tizen::Base::Boolean) pairs for the package filter @n
 339         * @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
 340         *                                                       The user defined key-value pairs can be added in <Metadata> of manifest.xml. @n For more information,
 341         *                                                       see <a href="../org.tizen.native.appprogramming/html/guide/app/package_filter.htm">the predefined key-value pairs
 342         *                                                       for package filter</a> and <a href="../org.tizen.native.appprogramming/html/guide/app/package_app_filter.htm">the
 343         *                                                       predefined key-value pairs for package app filter</a>.
 344         * @exception    E_SUCCESS                            The method is successful.
 345         * @exception    E_INVALID_ARG                        A specified input parameter is invalid.
 346         * @exception    E_SYSTEM                             The method cannot proceed due to a severe system error.
 347         * @exception    E_PRIVILEGE_DENIED                   The application does not have the privilege to call this method.
 348         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 349         */
 350         Tizen::Base::Collection::IList* GetPackageAppInfoListN(const Tizen::Base::Collection::IMap& packageFilterMap, const Tizen::Base::Collection::IMap& packageAppFilterMap) const;
 351
 352         /**
 353          * Gets the package manager instance.
 354          *
 355          * @since       2.0
 356          *
 357          * @return              A pointer to the %PackageManager instance, @n
 358          *                              else @c null
 359          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 360          */
 361         static PackageManager* GetInstance(void);
 362
 363 private:
 364         /**
 365          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 366          *
 367          * @since       2.0
 368          */
 369         PackageManager(void);
 370
 371         /**
 372          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 373          *
 374          * @since       2.0
 375          */
 376         virtual ~PackageManager(void);
 377
 378         /**
 379          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 380          *
 381          * @since       2.0
 382          */
 383         PackageManager(const PackageManager& rhs);
 384
 385         /**
 386          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 387          *
 388          * @since       2.0
 389          */
 390         PackageManager& operator =(const PackageManager& rhs);
 391
 392 private:
 393         class _PackageManagerImpl* __pPackageManagerImpl;
 394         friend class _PackageManagerImpl;
 395
 396 }; // PackageManager
 397
 398 } } } // Tizen::App::Package
 399
 400 #endif // _FAPP_PKG_PACKAGE_MANAGER_H_