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 a package and manages the package's 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 a package and retrieve the information of a package that is 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 an empty package ID if an error occurs @n
  77          *                              Checks with packageId.IsEmpty() whether the package ID is empty.
  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 @n
  91          *                              (%http://tizen.org/privilege/packageinfo is deprecated.)
  92          *
  93          * @return              An error code
  94          * @param[in]   listener                        The package installation event listener
  95          * @exception   E_SUCCESS                       The method is successful.
  96          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
  97          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
  98          */
  99         result AddPackageInstallationEventListener(IPackageInstallationEventListener& listener);
 100
 101         /**
 102          * Removes a package installation event listener.
 103          *
 104          * @since       2.0
 105          * @privlevel   public
 106          * @privilege   %http://tizen.org/privilege/package.info @n
 107          *                              (%http://tizen.org/privilege/packageinfo is deprecated.)
 108          *
 109          * @return              An error code
 110          * @param[in]   listener                        The package installation event listener
 111          * @exception   E_SUCCESS                       The method is successful.
 112          * @exception   E_OBJ_NOT_FOUND         Either of the following conditions has occurred:
 113          *                                                                      - The listener is not added.
 114          *                                                                      - The listener is already removed.
 115          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 116          */
 117         result RemovePackageInstallationEventListener(IPackageInstallationEventListener& listener);
 118
 119         /**
 120          * Gets the package information with the specific package ID.
 121          *
 122          * @since       2.0
 123          * @privlevel   public
 124          * @privilege   %http://tizen.org/privilege/package.info @n
 125          *                              (%http://tizen.org/privilege/packageinfo is deprecated.)
 126          *
 127          * @return              A pointer to the PackageInfo instance
 128          * @param[in]   packageId                               The package ID
 129          * @exception   E_SUCCESS                               The method is successful.
 130          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 131          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 132          * @exception   E_PKG_NOT_INSTALLED             The package has not been installed.
 133          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 134          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 135          */
 136         PackageInfo* GetPackageInfoN(const PackageId& packageId) const;
 137
 138         /**
 139          * Gets the application information with the specific application ID.
 140          *
 141          * @since       2.0
 142          * @privlevel   public
 143          * @privilege   %http://tizen.org/privilege/package.info @n
 144          *                              (%http://tizen.org/privilege/packageinfo is deprecated.)
 145          *
 146          * @return              A pointer to the PackageAppInfo instance
 147          * @param[in]   appId                           The application ID
 148          * @exception   E_SUCCESS                       The method is successful.
 149          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 150          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 151          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 152          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 153          */
 154         PackageAppInfo* GetPackageAppInfoN(const AppId& appId) const;
 155
 156         /**
 157          * Gets the package information list.
 158          *
 159          * @since       2.0
 160          * @privlevel   public
 161          * @privilege   %http://tizen.org/privilege/package.info @n
 162          *                              (%http://tizen.org/privilege/packageinfo is deprecated.)
 163          *
 164          * @return              A pointer to the list of the PackageInfo instances, @n
 165          *                              else @c null if it fails
 166          * @exception   E_SUCCESS                       The method is successful.
 167          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 168          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 169          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 170          */
 171         Tizen::Base::Collection::IList* GetPackageInfoListN(void) const;
 172
 173         /**
 174          * Checks whether a package is installed.
 175          *
 176          * @since       2.0
 177          * @privlevel   public
 178          * @privilege   %http://tizen.org/privilege/package.info @n
 179          *                              (%http://tizen.org/privilege/packageinfo is deprecated.)
 180          *
 181          * @return              @c true if the package is installed, @n
 182          *                              else @c false
 183          * @param[in]   packageId                       The package ID
 184          * @exception   E_SUCCESS                       The method is successful.
 185          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 186          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 187          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 188          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 189          */
 190         bool IsPackageInstalled(const PackageId& packageId) const;
 191
 192         /**
 193          * Installs a package. @n
 194          * The %InstallPackage() method operates asynchronously, that is, it ends immediately without an installation response.
 195          * 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.
 196          *
 197          * @since       2.0
 198          * @privlevel   platform
 199          * @privilege   %http://tizen.org/privilege/packagemanager.install
 200          *
 201          * @return              An error code
 202          * @param[in]   packageId                       The package ID
 203          * @param[in]   packagePath                     The package path
 204          * @param[in]   pListener                       The response listener
 205          * @exception   E_SUCCESS                       The method is successful.
 206          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 207          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 208          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 209          * @remarks
 210          *                      - A listener instance ownership is transferred to the platform.
 211          *                      - After notifying the result, the listener instance is removed automatically.
 212          *                      - A reuse of the listener instance is not allowed.
 213          */
 214         result InstallPackage(const PackageId& packageId, const Tizen::Base::String& packagePath, IPackageInstallationResponseListener* pListener);
 215
 216         /**
 217          * Uninstalls a package with the specified package ID. @n
 218          * The %UninstallPackage() method operates asynchronously, that is, it ends immediately without an uninstallation response.
 219          * 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.
 220          *
 221          * @since       2.0
 222          * @privlevel   platform
 223          * @privilege   %http://tizen.org/privilege/packagemanager.install
 224          *
 225          * @return              An error code
 226          * @param[in]   packageId                               The package ID
 227          * @param[in]   pListener                               The response listener
 228          * @exception   E_SUCCESS                               The method is successful.
 229          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 230          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 231          * @exception   E_PKG_NOT_INSTALLED             The package has not been installed.
 232          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 233          * @remarks
 234          *                      - A listener instance ownership is transferred to the platform.
 235          *                      - After notifying the result, the listener instance is removed automatically.
 236          *                      - A reuse of the listener instance is not allowed.
 237          */
 238         result UninstallPackage(const PackageId& packageId, IPackageUninstallationResponseListener* pListener);
 239
 240         /**
 241          * Moves a package with the specified package ID to the external storage.
 242          *
 243          * @since               2.0
 244          * @privlevel   platform
 245          * @privilege   %http://tizen.org/privilege/packagemanager.setting @n
 246          *                              (%http://tizen.org/privilege/packagesetting is deprecated.)
 247          *
 248          * @return              An error code
 249          * @param[in]   packageId                               The package ID
 250          * @exception   E_SUCCESS                               The method is successful.
 251          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 252          * @exception   E_INVALID_OPERATION             The package is already installed in the external storage.
 253          * @exception   E_STORAGE_FULL                  The storage is full.
 254          * @exception   E_PKG_NOT_INSTALLED             The package has not been installed.
 255          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 256          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 257          */
 258         result MoveToExternalStorage(const PackageId& packageId);
 259
 260         /**
 261          * Moves a package with the specified package ID to the internal storage.
 262          *
 263          * @since               2.0
 264          * @privlevel   platform
 265          * @privilege   %http://tizen.org/privilege/packagemanager.setting @n
 266          *                              (%http://tizen.org/privilege/packagesetting is deprecated.)
 267          *
 268          * @return              An error code
 269          * @param[in]   packageId                               The package ID
 270          * @exception   E_SUCCESS                               The method is successful.
 271          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 272          * @exception   E_INVALID_OPERATION             The package is already installed in the internal storage.
 273          * @exception   E_STORAGE_FULL                  The storage is full.
 274          * @exception   E_PKG_NOT_INSTALLED             The package has not been installed.
 275          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 276          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 277          */
 278         result MoveToInternalStorage(const PackageId& packageId);
 279
 280         /**
 281         * Gets the package information from a specific file. @n
 282         * The supported file extensions are tpk and wgt.
 283         *
 284         * @since         2.1
 285         * @privlevel     platform
 286         * @privilege     %http://tizen.org/privilege/packagemanager.info
 287         *
 288         * @return        A pointer to the PackageInfo instance, @n
 289         *                else @c null if it fails
 290         * @param[in]     filePath                           The package file path
 291         * @exception     E_SUCCESS                          The method is successful.
 292         * @exception     E_INVALID_ARG                      The specified input parameter is invalid.
 293         * @exception     E_FILE_NOT_FOUND                   The specified file cannot be found or accessed.
 294         * @exception     E_UNSUPPORTED_FORMAT               The specified format is invalid or not supported.
 295         * @exception     E_PARSING_FAILED                   The method has failed to parse the package file or xml file(s) inside the package.
 296         * @exception     E_PRIVILEGE_DENIED                 The application does not have the privilege to call this method.
 297         * @remarks       The specific error code can be accessed using the GetLastResult() method.
 298         */
 299         PackageInfo* GetPackageInfoFromFileN(const Tizen::Base::String& filePath) const;
 300
 301         /**
 302         * Gets the package information list using the package filter.
 303         *
 304         * @since         2.1
 305         * @privlevel     public
 306         * @privilege     %http://tizen.org/privilege/package.info
 307         *
 308         * @return        A pointer to the list of the PackageInfo instances, @n
 309         *                else @c null if it fails
 310         * @param[in]     packageFilterMap         The predefined key(Tizen::Base::String)-value(Tizen::Base::Boolean) pairs for the package filter @n
 311         *                                                                                 For more information on the predefined key-value pairs for the package filter,
 312         *                                                                         see <a href="../org.tizen.native.appprogramming/html/guide/app/package_app_filter.htm">the predefined key-value pairs for the package filter</a>.
 313         * @exception    E_SUCCESS                 The method is successful.
 314         * @exception    E_INVALID_ARG             The specified input parameter is invalid.
 315         * @exception    E_SYSTEM                  The method cannot proceed due to a severe system error.
 316         * @exception    E_PRIVILEGE_DENIED        The application does not have the privilege to call this method.
 317         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 318         */
 319         Tizen::Base::Collection::IList* GetPackageInfoListN(const Tizen::Base::Collection::IMap& packageFilterMap) const;
 320
 321         /**
 322         * Gets the application information list using the package application filter.
 323         *
 324         * @since         2.1
 325         * @privlevel     public
 326         * @privilege     %http://tizen.org/privilege/package.info
 327         *
 328         * @return        A pointer to the list of the PackageAppInfo instances, @n
 329         *                else @c null if it fails
 330         * @param[in]     packageAppFilterMap      The predefined key(Tizen::Base::String)-value(Tizen::Base::String or Tizen::Base::Boolean) pairs for the package application filter @n
 331         *                                                                                 For more information, see <a href="../org.tizen.native.appprogramming/html/guide/app/package_app_filter.htm">
 332         *                                                                                 the predefined key-value pairs for the package application filter</a>.
 333         * @exception    E_SUCCESS                 The method is successful.
 334         * @exception    E_INVALID_ARG             The specified input parameter is invalid.
 335         * @exception    E_SYSTEM                  The method cannot proceed due to a severe system error.
 336         * @exception    E_PRIVILEGE_DENIED        The application does not have the privilege to call this method.
 337         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 338         */
 339         Tizen::Base::Collection::IList* GetPackageAppInfoListN(const Tizen::Base::Collection::IMap& packageAppFilterMap) const;
 340
 341         /**
 342         * Gets the application information list using the package filter and the package application filter.
 343         *
 344         * @since         2.1
 345         * @privlevel     public
 346         * @privilege     %http://tizen.org/privilege/package.info
 347         *
 348         * @return        A pointer to the list of the PackageAppInfo instances, @n
 349         *                else @c null if it fails
 350         * @param[in] packageFilterMap        The predefined key(Tizen::Base::String)-value(Tizen::Base::Boolean) pairs for the package filter @n
 351         * @param[in] packageAppFilterMap     The predefined and user defined key(Tizen::Base::String)-value(%Tizen::Base::String or Tizen::Base::Boolean) pairs for the package application filter @n
 352         *                                                                        The user defined key-value pairs can be added in the <Metadata> of the manifest.xml. @n For more information,
 353         *                                                                        see <a href="../org.tizen.native.appprogramming/html/guide/app/package_filter.htm">the predefined key-value pairs
 354         *                                                                        for the package filter</a>, and <a href="../org.tizen.native.appprogramming/html/guide/app/package_app_filter.htm">the
 355         *                                                                        predefined key-value pairs for the package application filter</a>.
 356         * @exception    E_SUCCESS            The method is successful.
 357         * @exception    E_INVALID_ARG        A specified input parameter is invalid.
 358         * @exception    E_SYSTEM             The method cannot proceed due to a severe system error.
 359         * @exception    E_PRIVILEGE_DENIED   The application does not have the privilege to call this method.
 360         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 361         */
 362         Tizen::Base::Collection::IList* GetPackageAppInfoListN(const Tizen::Base::Collection::IMap& packageFilterMap, const Tizen::Base::Collection::IMap& packageAppFilterMap) const;
 363
 364         /**
 365          * Gets a pointer to the %PackageManager instance.
 366          *
 367          * @since       2.0
 368          *
 369          * @return              A pointer to the %PackageManager instance, @n
 370          *                              else @c null if it fails
 371          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 372          */
 373         static PackageManager* GetInstance(void);
 374
 375 private:
 376         /**
 377          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 378          *
 379          * @since       2.0
 380          */
 381         PackageManager(void);
 382
 383         /**
 384          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 385          *
 386          * @since       2.0
 387          */
 388         virtual ~PackageManager(void);
 389
 390         /**
 391          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 392          *
 393          * @since       2.0
 394          */
 395         PackageManager(const PackageManager& rhs);
 396
 397         /**
 398          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 399          *
 400          * @since       2.0
 401          */
 402         PackageManager& operator =(const PackageManager& rhs);
 403
 404 private:
 405         class _PackageManagerImpl* __pPackageManagerImpl;
 406         friend class _PackageManagerImpl;
 407
 408 }; // PackageManager
 409
 410 } } } // Tizen::App::Package
 411
 412 #endif // _FAPP_PKG_PACKAGE_MANAGER_H_