inc/FAppAppManager.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        FAppAppManager.h
  19  * @brief       This is the header file for the %AppManager class.
  20  *
  21  * This header file contains the declarations of the %AppManager class.
  22  */
  23
  24 #ifndef _FAPP_APP_MANAGER_H_
  25 #define _FAPP_APP_MANAGER_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FAppTypes.h>
  29
  30 namespace Tizen { namespace Base {
  31 class ByteBuffer;
  32 namespace Collection {
  33 class IList;
  34 class IMap;
  35 }
  36 }}
  37
  38 namespace Tizen { namespace App
  39 {
  40
  41 class IAppControlEventListener;
  42 class IAppControlListener;
  43 class IAppControlResponseListener;
  44 class IAppCheckpointEventListener;
  45 class IAppLaunchConditionEventListener;
  46 class IActiveAppEventListener;
  47 class AppControl;
  48 class SqlDataControl;
  49 class MapDataControl;
  50
  51 /**
  52  * @class               AppManager
  53  * @brief               This class manages all the applications.
  54  *
  55  * @since       2.0
  56  *
  57  * @final       This class is not intended for extension.
  58  *
  59  * The %AppManager class manages all the applications.
  60  * The application manager supports normal and conditional application launch, and application control search and launch.
  61  * It looks up the specific application control from the application control registry and creates an application control instance.
  62  * @n
  63  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/launching_other_apps_within_apps.htm">Launching Other Applications</a> and <a href="../org.tizen.native.appprogramming/html/guide/app/registering_launch_condition.htm">Registering a Launch Condition</a>, and <a href="../org.tizen.native.appprogramming/html/guide/app/app_controls.htm">Application Controls</a>.
  64  */
  65 class _OSP_EXPORT_ AppManager
  66         : public Tizen::Base::Object
  67 {
  68 public:
  69         /**
  70          * @enum LaunchOption
  71          *
  72          * Defines the launch options.
  73          *
  74          * @since       2.0
  75          */
  76         enum LaunchOption
  77         {
  78                 LAUNCH_OPTION_DEFAULT   /**< The launch option: default */
  79         };
  80
  81         /**
  82          * Finds the application control that the caller wants to start. @n
  83          * It resolves the matched application control with the delivered application ID and operation ID.
  84          *
  85          * @since       2.0
  86          *
  87          * @return      A pointer to the newly created AppControl instance if a matched %AppControl is found, @n
  88          *                      else @c null
  89          * @param[in]   appId                   The application ID
  90          * @param[in]   operationId             The operation ID
  91          * @exception   E_SUCCESS               The method is successful.
  92          * @exception   E_OBJ_NOT_FOUND The application control is not found.
  93          * @exception   E_SYSTEM                A system error has occurred. @n
  94          *                                                              Either the file operation or the DB operation has failed.
  95          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  96          * @remarks     %Tizen platform defines platform-defined alias for application ID and this aliased application ID
  97          *                      can be used to find the AppControl. For more information, see
  98          *                      <a href="../org.tizen.native.appprogramming/html/guide/app/app_controls.htm">here</a>.
  99          *
 100          * The following example demonstrates how to use the %FindAppControlN() method to find the application control.
 101          *
 102          * @code
 103          * String telUri = L"tel:12345678900";
 104          *
 105          * AppControl* pAc = AppManager::FindAppControlN(L"tizen.phone", L"http://tizen.org/appcontrol/operation/dial");
 106          * pAc->Start(&telUri, null, null, null);
 107          * @endcode
 108          */
 109         static AppControl* FindAppControlN(const AppId& appId, const Tizen::Base::String& operationId);
 110
 111         /**
 112          * Finds a list of AppControl instances that matches the specified operation ID, category,
 113          * data type, and URI pattern.
 114          *
 115          * @since               2.0
 116          *
 117          * @return      A pointer to the list of the AppControl instances that matches the specified operation ID, category, URI, and data type, @n
 118          *          else @c null if it fails
 119          * @param[in]   pOperationId    The operation ID
 120          * @param[in]   pCategory                       The application category
 121          * @param[in]   pDataType       The MIME type (RFC 2046) or file extension @n
 122          *                          The '.' prefix must be used when specifying the file extension.
 123          * @param[in]   pUriPattern                     The URI pattern
 124          *
 125          * @exception   E_SUCCESS                       The method is successful.
 126          * @exception   E_INVALID_ARG           At least one of the specified @c pOperationId, @c pCategory, @c pDataType, or @c pUriScheme must not be @c null.
 127          * @exception   E_INVALID_FORMAT        The specified URI scheme is invalid (RFC 2396).
 128          * @exception   E_UNSUPPORTED_FORMAT    The specified file extension for @c pDataType is not supported.
 129          * @exception   E_OBJ_NOT_FOUND         The application control is not found.
 130          * @exception   E_SYSTEM                A system error has occurred. @n
 131          *                                                              Either the file operation or the DB operation has failed.
 132          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 133          */
 134         static Tizen::Base::Collection::IList* FindAppControlsN(const Tizen::Base::String* pOperationId, const Tizen::Base::String* pCategory, const Tizen::Base::String* pDataType, const Tizen::Base::String* pUriPattern);
 135
 136         /**
 137      * @if OSPDEPREC
 138          * Starts the application control if there is only one application control that matches the specified URI, operation ID, and data type. @n
 139          * If there are more than one application controls, the one that the user selects is started.
 140          *
 141          * @brief       <i> [Deprecated] </i>
 142          * @deprecated  This method is deprecated because IAppControlListener is deprecated and replaced by IAppControlResponselistener.
 143          *                              Instead of using this method, use AppControl::FindAndStart().
 144          * @since               2.0
 145          * @privlevel   public
 146          * @privilege   %http://tizen.org/privilege/application.launch
 147          *
 148          * @return      An error code
 149          * @param[in]   uriData                 The URI that has a maximum size of @c 1024 bytes
 150          * @param[in]   pOperationId    The operation ID
 151          * @param[in]   pDataType       The MIME type (RFC 2046) or file extension @n
 152          *                          The '.' prefix must be used for the @c dataType when specifying the file extension.
 153          * @param[in]   pListener       A listener that gets notified when the resolved application control has started
 154          * @exception   E_SUCCESS                       The method is successful.
 155          * @exception   E_MAX_EXCEEDED          The size of @c uri has exceeded the maximum limit.
 156          * @exception   E_UNSUPPORTED_FORMAT    The specified file extension for @c pDataType is not supported.
 157          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 158          * @exception   E_OBJ_NOT_FOUND         The application control is not found.
 159          * @exception   E_IN_PROGRESS           The target application control is in progress.
 160          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 161          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 162          *
 163          * @see App::GetAppArgumentListN()
 164          * @see FindAppControlN()
 165          * @see FindAppControlsN()
 166          * @see AppControl::Start()
 167          *
 168          * The following example demonstrates how to use the %StartAppControl() method.
 169          * @code
 170          * String operationId = L"http://tizen.org/appcontrol/operation/call";
 171          * StartAppControl(L"tel:1234567890", &operationId, null, null);
 172          * @endcode
 173      * @endif
 174          */
 175         static result StartAppControl(const Tizen::Base::String& uriData, const Tizen::Base::String* pOperationId, const Tizen::Base::String* pDataType, IAppControlListener* pListener);
 176
 177         /**
 178          * @if OSPDEPREC
 179          * Starts the application control if there is only one application control that matches the specified operation ID, category, URI, and data type. @n
 180          * If there are more than one application controls, the one that the user selects is started.
 181          *
 182          * @brief       <i> [Deprecated] </i>
 183          * @deprecated  This method is deprecated because IAppControlListener is deprecated and replaced by IAppControlResponselistener.
 184          *                              Instead of using this method, use AppControl::FindAndStart().
 185          * @since               2.0
 186          * @privlevel   public
 187          * @privilege   %http://tizen.org/privilege/application.launch
 188          *
 189          * @return      An error code
 190          * @param[in]   pOperationId    The operation ID
 191          * @param[in]   pCategory                       The application control category
 192          * @param[in]   pDataType       The MIME type (RFC 2046) or file extension @n
 193          *                          The '.' prefix must be used when specifying the file extension.
 194          * @param[in]   pUriPattern                     A URI pattern which is used for application control resolution and delivered as the argument
 195          * @param[in]   pDataList       The data list that is delivered to the resolved application control @n
 196          *                       It has a maximum size of @c 1024 bytes.
 197          * @param[in]   pListener       A listener that gets notified when the resolved application control has started
 198          * @exception   E_SUCCESS                       The method is successful.
 199          * @exception   E_INVALID_ARG           At least one of the specified @c pOperationId, @c pCategory, @c pDataType, or @c pUri must not be @c null.
 200          * @exception   E_MAX_EXCEEDED          The size of @c pDataList has exceeded the maximum limit.
 201          * @exception   E_UNSUPPORTED_FORMAT    The specified file extension for @c pDataType is not supported.
 202          * @exception   E_OBJ_NOT_FOUND         The application control is not found.
 203          * @exception   E_IN_PROGRESS           The target application control is in progress.
 204          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 205          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 206          * @remarks             For delivered launch arguments, see App::GetAppArgumentListN().
 207          * @see App::GetAppArgumentListN()
 208          * @see FindAppControlsN()
 209          * @see AppControl::Start()
 210          * @endif
 211          */
 212         static result StartAppControl(const Tizen::Base::String* pOperationId, const Tizen::Base::String* pCategory, const Tizen::Base::String* pDataType, const Tizen::Base::String* pUriPattern, const Tizen::Base::Collection::IList* pDataList, IAppControlListener* pListener);
 213
 214         /**
 215          * Gets the SQL-type data control that the caller wants to use. @n
 216          * It resolves the matching data control with the specified data control provider ID.
 217          *
 218          * @since       2.0
 219          *
 220          * @return              A pointer to the SqlDataControl instance if a matching data control is found, @n
 221          *                              else @c null
 222          * @param[in]   providerId                      The provider ID
 223          * @exception   E_SUCCESS                       The method is successful.
 224          * @exception   E_OBJ_NOT_FOUND         The data control specified with the @c providerId is not found.
 225          * @exception   E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 226          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 227          * @exception   E_SYSTEM                        A system error has occurred.
 228          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 229          */
 230         static SqlDataControl* GetSqlDataControlN(const Tizen::Base::String& providerId);
 231
 232         /**
 233          * Gets the MAP-type data control that the caller wants to use. @n
 234          * It resolves the matching data control with the specified data control provider ID.
 235          *
 236          * @since       2.0
 237          *
 238          * @return              A pointer to the MapDataControl instance if a matching data control is found, @n
 239          *                              else @c null
 240          * @param[in]   providerId                      The provider ID
 241          * @exception   E_SUCCESS                       The method is successful.
 242          * @exception   E_OBJ_NOT_FOUND         The data control specified with the @c providerId is not found.
 243          * @exception   E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 244          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 245          * @exception   E_SYSTEM                        A system error has occurred.
 246          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 247          */
 248         static MapDataControl* GetMapDataControlN(const Tizen::Base::String& providerId);
 249
 250         /**
 251         * Gets the path of the read-only shared directory exported by an other application specified with an application ID.
 252         *
 253         * @since        2.0
 254         *
 255         * @return               The other application's shared directory path, @n
 256         *                               else an empty string if an exception occurs
 257         * @param[in]    appId                           The application ID
 258         * @exception    E_SUCCESS                       The method is successful.
 259         * @exception    E_APP_NOT_INSTALLED     The expected shared directory cannot be found
 260         *                                                                       because the application specified with @c appId cannot be installed.
 261         * @remarks
 262         *                               - The returned path can be invalid when the application with specified with @c appId is uninstalled.
 263         *                               - The specific error code can be accessed using the GetLastResult() method.
 264         */
 265         static Tizen::Base::String GetAppSharedPath(const AppId& appId);
 266
 267         /**
 268          * Gets the application manager instance.
 269          *
 270          * @since       2.0
 271          *
 272          * @return      A pointer to the %AppManager instance, @n
 273          *                      else @c null if it fails
 274          */
 275         static AppManager* GetInstance(void);
 276
 277         /**
 278          * @if OSPDEPREC
 279          * Launches the default application with the given @c appId. @n
 280          * The launch arguments are given as App::OnUserEventReceivedN() or can be obtained by
 281          * invoking App::GetAppArgumentListN(), especially within App::OnAppInitializing().
 282          *
 283          * @brief               <i> [Deprecated] </i>
 284          * @deprecated  This method is deprecated because sending argument with %LaunchApplication() is not recommended. @n
 285          *                              Instead of using this method, use %LaunchApplication() without launch arguments or AppControl::Start().
 286          * @since       2.0
 287          * @privlevel   public
 288          * @privilege   %http://tizen.org/privilege/application.launch
 289          *
 290          * @return      An error code
 291          * @param[in]   appId                           The application's ID to execute
 292          * @param[in]   pArguments                      A pointer to the list of string arguments that has a maximum size of @c 1024 bytes
 293          * @param[in]   option                          The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 294          * @exception   E_SUCCESS                       The method is successful.
 295          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 296          * @exception   E_INVALID_ARG           The specified @c appId is empty.
 297          * @exception   E_OBJ_NOT_FOUND         The target application is not installed.
 298          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 299          * @exception   E_MAX_EXCEEDED          The size of @c appId or @c pArguments has exceeded the maximum limit.
 300          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 301          * @exception E_ILLEGAL_ACCESS                          The application is not signed with the same certificate of target application. @b Since: @b 2.1
 302          * @endif
 303          */
 304         result LaunchApplication(const AppId& appId, const Tizen::Base::Collection::IList* pArguments, LaunchOption option = LAUNCH_OPTION_DEFAULT);
 305
 306         /**
 307          * Launches the default application with the given @c appId.
 308          *
 309          * @since       2.0
 310          * @privlevel   public
 311          * @privilege   %http://tizen.org/privilege/application.launch
 312          *
 313          * @return      An error code
 314          * @param[in]   appId                           The application's ID to execute
 315          * @param[in]   option                          The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 316          * @exception   E_SUCCESS                       The method is successful.
 317          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 318          * @exception   E_APP_NOT_INSTALLED     The target application is not installed.
 319          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 320          * @exception E_ILLEGAL_ACCESS                          The application is not signed with the same certificate of target application. @b Since: @b 2.1
 321          */
 322         result LaunchApplication(const AppId& appId, LaunchOption option = LAUNCH_OPTION_DEFAULT);
 323
 324         /**
 325          * Terminates an application.
 326          *
 327          * @since       2.0
 328          * @privlevel   partner
 329          * @privilege   %http://tizen.org/privilege/appmanager.kill @n
 330          *                              (%http://tizen.org/privilege/application.kill is deprecated.)
 331          *
 332          * @return      An error code
 333          * @param[in]   appId                           The application's ID to execute
 334          * @exception   E_SUCCESS                       The method is successful.
 335          * @exception   E_SYSTEM                        A system error has occurred.
 336          * @exception   E_OBJ_NOT_FOUND         The application is either not installed or is not running.
 337          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 338          */
 339         result TerminateApplication(const AppId& appId);
 340
 341         /**
 342          * Checks whether an application is running.
 343          *
 344          * @since       2.0
 345          *
 346          * @return      @c true if the application is running, @n
 347          *           else @c false
 348          * @param[in]   appId               The installed application ID
 349          */
 350         bool IsRunning(const AppId& appId) const;
 351
 352         /**
 353          * Gets a list of running applications at the time of invocation.
 354          *
 355          * @since      2.0
 356          *
 357          * @return      A pointer to the running state application list (AppId), @n
 358          *                   else @c null if an error occurs
 359          * @exception   E_SUCCESS                       The method is successful.
 360          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 361          * @exception   E_SYSTEM                        A system error has occurred.
 362          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 363          */
 364         Tizen::Base::Collection::IList* GetRunningAppListN(void) const;
 365
 366         /**
 367          * Registers an application with a specific condition and launches it if the condition is met. @n
 368          * If the requested application is already running, the application is notified through IAppLaunchConditionEventListener::OnAppLaunchConditionMetN().
 369          * The launch arguments are given as input parameters to %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN().
 370          *
 371          * @since       2.0
 372          * @privlevel   public
 373          * @privilege   %http://tizen.org/privilege/application.launch
 374          * @feature     %http://tizen.org/feature/network.nfc for L"NFC='command'" or %http://tizen.org/feature/usb.accessory for "Serial='command'" in the value of @c condition
 375          *
 376          * @return              An error code
 377          * @param[in]   condition         The launch condition for the application @n
 378          *                                                        The condition has L"Key='value'" format and is case sensitive. To use single or double quotes in the condition values, prefix them with a slash (\' or \"). @n
 379          *                                                        For more information on the condition formats, see <a href="../org.tizen.native.appprogramming/html/guide/app/registering_launch_condition.htm">Registering a Launch Condition</a>.
 380          *                            <table><tr><th>Condition Format</th><th>Meaning</th></tr>
 381                                       <tr><td>L"DateTime='mm/dd/yyyy hh:mm:ss'"</td>
 382                                       <td>The specified condition is the local due time.</td></tr>
 383                                       <tr><td>L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'"</td>
 384                                       <td>The specific condition is the time period after due time.</td></tr>
 385                                       <tr><td>L"WeeklyTime='EEE HH:mm:ss'"</td>
 386                                       <td>The specified condition is a day of a week with a specific time at which the application is launched on a weekly basis. For multiple descriptions, "," delimiter can be used as shown in the following example: <br>i"'Mon 09:00:00', 'Tue 09:00:00', 'Wed 09:00:00', 'Thu 09:00:00', 'Fri 09:00:00'"<br> To specify the day of the week, it must be in one of the following supported string format: <br>Mon: Monday<br>Tue: Tuesday<br>Wed: Wednesday<br>Thu: Thursday<br>Fri: Friday<br>Sat: Saturday<br>Sun: Sunday</td></tr>
 387                                       <tr><td>L"Serial='command'"</td><td>The specified condition is a serial
 388                                       communication input command.</td></tr>
 389                                       <tr><td>L"NFC='command'"</td><td>The specified condition is a Near Field Communication (NFC) tag that has the NFC Data Exchange Format (NDEF) data.
 390                                       </td></tr></table> @n
 391
 392          *
 393          * @param[in]   pArguments        A list of string arguments that has a maximum size of @c 1024 bytes @n
 394          *                                                        The parameter can also contain @c null. @n
 395          *                                                    For more information on the arguments, see <a href="../org.tizen.native.appprogramming/html/guide/app/launching_other_apps_within_apps.htm">Launching Other Applications</a>.
 396          * @param[in]   option         The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 397          * @exception   E_SUCCESS                       The method is successful.
 398          * @exception   E_INVALID_ARG           The launch condition is empty or too long (Maximum 400 bytes).
 399          * @exception   E_INVALID_FORMAT                The specified condition format is invalid.
 400          * @exception   E_INVALID_CONDITION  The specified condition format is valid but the condition has at least one or more invalid values.
 401          * @exception   E_OBJ_ALREADY_EXIST     The specified @c condition is already registered by a different application.
 402          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 403          * @exception   E_MAX_EXCEEDED          The size of @c pArguments has exceeded the maximum limit.
 404          * @exception   E_SYSTEM                                A system error has occurred.
 405          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 406          * @exception   E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature. For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>. @b Since: @b 2.1
 407          *
 408          * @remarks             When the registered application is about to be launched, the registered launch condition and arguments are given as parameters to IAppLaunchConditionEventListener::OnAppLaunchConditionMetN().
 409          * @remarks             The newly introduced launch condition does not work on the previous SDK version and the E_INVALID_CONDITION exception is returned.
 410          * @remarks             Registering the same launch condition overwrites the previous launch argument without throwing an exception.
 411          * @remarks             The launch period requires more consideration because an inappropriate short period value may lead
 412          *                              to an adverse effect on the device battery.
 413          * @remarks             For the NFC launch condition, the detected NDEF message can be acquired using the @c pExtraData parameter of the %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 414          * @remarks             Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 415          * @see                 UnregisterAppLaunch()
 416          * @see                 IsAppLaunchRegistered()
 417          * @see                 LaunchApplication(const AppId&, LaunchOption);
 418          * @see                 Tizen::Base::DateTime::ToString()
 419          * @see                 Tizen::Io::SerialPort
 420          *
 421          * The following example demonstrates how to use the %RegisterAppLaunch() method.
 422          *
 423          * @code
 424          *
 425          *  DateTime time;
 426          *  SystemTime::GetCurrentTime(TIME_MODE_WALL, time);
 427          *  time.AddMinutes(1);
 428          *
 429          *  String cond;
 430          *  cond.Format(70, L"DueTime='%S' LaunchPeriod='60'", time.ToString().GetPointer());
 431          *
 432          *  // Registers a periodic condition that fires every 60 minutes starting after one minute
 433          *  AppManager::GetInstance()->RegisterAppLaunch(cond, null, AppManager::LAUNCH_OPTION_DEFAULT)
 434          *
 435          * @endcode
 436          */
 437         result RegisterAppLaunch(const Tizen::Base::String& condition, const Tizen::Base::Collection::IList* pArguments, LaunchOption option);
 438
 439         /**
 440          * Unregisters the previously registered launch condition.
 441          *
 442          * @since       2.0
 443          * @privlevel   public
 444          * @privilege   %http://tizen.org/privilege/application.launch
 445          *
 446          * @return              An error code
 447          * @exception   E_SUCCESS                       Either of the following conditions has occurred:
 448          *                                                                      - The method is successful.
 449          *                                                                      - There is no registered launch condition.
 450          * @exception   E_SYSTEM                        A system error has occurred.
 451          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 452          * @see                 RegisterAppLaunch()
 453          * @see                 IsAppLaunchRegistered()
 454          */
 455         result UnregisterAppLaunch(void);
 456
 457         /**
 458          * Unregisters the specified launch condition.
 459          *
 460          * @since               2.0
 461          * @privlevel   public
 462          * @privilege   %http://tizen.org/privilege/application.launch
 463          *
 464          * @return              An error code
 465          * @param[in]   condition                       The launch condition for the application
 466          * @exception   E_SUCCESS                       The method is successful.
 467          * @exception   E_OBJ_NOT_FOUND         The specified launch condition is not found.
 468          * @exception   E_SYSTEM                        A system error has occurred.
 469          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 470          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 471          * @see                 RegisterAppLaunch()
 472          * @see                 IsAppLaunchRegistered()
 473          */
 474         result UnregisterAppLaunch(const Tizen::Base::String& condition);
 475
 476         /**
 477          * Checks whether a launch condition is registered for the application.
 478          *
 479          * @since       2.0
 480          *
 481          * @return     @c true if a condition is already registered to the application invoking this method, @n
 482          *             else @c false
 483          * @exception  E_SUCCESS                        The method is successful.
 484          * @exception  E_SYSTEM                         A system error has occurred.
 485          *
 486          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 487          * @see         RegisterAppLaunch()
 488          * @see         UnregisterAppLaunch()
 489          */
 490         bool IsAppLaunchRegistered(void) const;
 491
 492         /**
 493          * Registers the specified application with a specific condition and launches it if the condition is met. @n
 494          * If the requested application is already running, the application is notified through IAppLaunchConditionEventListener::OnAppLaunchConditionMetN().
 495          * The launch arguments are given as input parameters to %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN().
 496          *
 497          * @since               2.0
 498          * @privlevel   partner
 499          * @privilege   %http://tizen.org/privilege/appmanager.launch
 500          * @feature     %http://tizen.org/feature/network.nfc for L"NFC='command'" or %http://tizen.org/feature/usb.accessory for L"Serial='command'" in the value of @c condition
 501          *
 502          * @return     An error code
 503          * @param[in]  appId          The ID of the application registered for launch
 504          * @param[in]  condition      The launch condition for the application @n
 505          *                                The condition has L"Key='value'" format and is case sensitive. To use single or double quotes in the condition values, prefix them with a slash (\' or \"). @n
 506          *                                                        For more information on the condition formats, see <a href="../org.tizen.native.appprogramming/html/guide/app/registering_launch_condition.htm">Registering a Launch Condition</a>.
 507          *                             <table><tr><th>Condition Format</th><th>Meaning</th></tr>
 508                                      <tr><td>L"DateTime='mm/dd/yyyy hh:mm:ss'"</td>
 509                                      <td>The specified condition is the local due time.</td></tr>
 510                                      <tr><td>L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'"</td>
 511                                      <td>The specific condition is the time period after due time.</td></tr>
 512                                      <tr><td>L"WeeklyTime='EEE HH:mm:ss'"</td>
 513                                      <td>The specified condition is a day of a week with a specific time at which the application is launched on a weekly basis. For multiple descriptions, "," delimiter can be used as shown in the following example: <br>i"'Mon 09:00:00', 'Tue 09:00:00', 'Wed 09:00:00', 'Thu 09:00:00', 'Fri 09:00:00'"<br> To specify the day of the week, it must be in one of the following supported string format: <br>Mon: Monday<br>Tue: Tuesday<br>Wed: Wednesday<br>Thu: Thursday<br>Fri: Friday<br>Sat: Saturday<br>Sun: Sunday</td></tr>
 514                                      <tr><td>L"Serial='command'"</td><td>The specified condition is a serial
 515                                      communication input command.</td></tr>
 516                                      <tr><td>L"NFC='command'"</td><td>The specified condition is a Near Field Communication (NFC) tag that has the NFC Data Exchange Format (NDEF) data.
 517                                      </td></tr></table> @n
 518
 519          *
 520          * @param[in]  pArguments         A list of string arguments that has a maximum size of @c 1024 bytes @n
 521          *                                                        The parameter can also contain @c null. @n
 522          *                                                    For more information on the arguments, see <a href="../org.tizen.native.appprogramming/html/guide/app/launching_other_apps_within_apps.htm">Launching Other Applications</a>.
 523          * @param[in]  option         The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 524          * @exception  E_SUCCESS                        The method is successful.
 525          * @exception  E_APP_NOT_INSTALLED      The application is not installed.
 526          * @exception  E_INVALID_ARG            The launch condition is empty or too long (Maximum 400 bytes).
 527          * @exception  E_INVALID_FORMAT         The specified condition format is invalid.
 528          * @exception  E_INVALID_CONDITION  The specified condition format is valid but the condition has at least one or more invalid values.
 529          * @exception  E_OUT_OF_MEMORY          The memory is insufficient.
 530          * @exception  E_MAX_EXCEEDED           The size of @c pArguments has exceeded the maximum limit.
 531          * @exception  E_SYSTEM                         A system error has occurred.
 532          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 533          * @exception    E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature. For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>. @b Since: @b 2.1
 534          *
 535          * @remarks    When the registered application is about to be launched, the registered launch condition and arguments are given as parameters to IAppLaunchConditionEventListener::OnAppLaunchConditionMetN().
 536          * @remarks    The newly introduced launch condition does not work on the previous SDK version and the @c E_INVALID_CONDITION exception is returned.
 537          * @remarks    Registering the same launch condition overwrites the previous launch argument without throwing an exception.
 538          * @remarks    The launch period requires more consideration because an inappropriate short period value may lead
 539          *             to an adverse effect on the device battery.
 540          * @remarks    For the NFC launch condition, the detected NDEF message can be acquired using the @c pExtraData parameter of the %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 541          * @remarks     Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 542          * @see        UnregisterAppLaunch()
 543          * @see        IsAppLaunchRegistered()
 544          * @see        LaunchApplication(const AppId&, LaunchOption);
 545          * @see        IAppLaunchConditionEventListener::OnAppLaunchConditionMetN()
 546          * @see        Tizen::Base::DateTime::ToString()
 547          * @see        Tizen::Io::SerialPort
 548          */
 549         result RegisterAppLaunch(const AppId& appId, const Tizen::Base::String& condition, const Tizen::Base::Collection::IList* pArguments, LaunchOption option);
 550
 551         /**
 552          * Unregisters the launch condition.
 553          *
 554          * @since               2.0
 555          * @privlevel   partner
 556          * @privilege   %http://tizen.org/privilege/appmanager.launch
 557          *
 558          * @return     An error code
 559          * @param[in]  appId          The application ID
 560          * @param[in]  pCondition           The launch condition to unregister @n
 561          *                                  If the parameter contains @c null, all the conditions are unregistered.
 562          * @exception  E_SUCCESS                        The method is successful.
 563          * @exception  E_APP_NOT_INSTALLED      The application is not installed.
 564          * @exception  E_OBJ_NOT_FOUND          The specified launch condition is not found.
 565          * @exception  E_SYSTEM                         A system error has occurred.
 566          * @exception  E_OUT_OF_MEMORY          The memory is insufficient.
 567          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 568          *
 569          * @see         RegisterAppLaunch()
 570          * @see         IsAppLaunchRegistered()
 571          */
 572         result UnregisterAppLaunch(const AppId& appId, const Tizen::Base::String* pCondition);
 573
 574         /**
 575          * Checks whether a previously registered launch condition is present for the specified application.
 576          *
 577          * @since               2.0
 578          * @privlevel   partner
 579          * @privilege   %http://tizen.org/privilege/appmanager.launch
 580          *
 581          * @return     @c true if a condition is already registered to the specified application with the specified condition, @n
 582          *             else @c false
 583          * @param[in]  appId          The application ID
 584          * @param[in]  pCondition     The launch condition to register for the specified @c appId @n
 585          *                            If the parameter contains @c null, the method checks for any registered launch condition for the specified @c appId.
 586          * @exception  E_SUCCESS                        The method is successful.
 587          * @exception  E_APP_NOT_INSTALLED      The application is not installed.
 588          * @exception  E_SYSTEM                         A system error has occurred.
 589          * @exception  E_OUT_OF_MEMORY          The memory is insufficient.
 590          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 591          *
 592          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 593          * @see         RegisterAppLaunch()
 594          * @see         UnregisterAppLaunch()
 595          */
 596         bool IsAppLaunchRegistered(const AppId& appId, const Tizen::Base::String* pCondition = null) const;
 597
 598         /**
 599          * Sets a checkpoint event listener. @n
 600          * The listener gets notified when a checkpoint event is fired.
 601          *
 602          * @since       2.0
 603          *
 604          * @return      An error code
 605          * @param[in]   listener                The listener to receive the checkpoint event
 606          * @exception  E_SUCCESS                        The method is successful.
 607          * @exception  E_OBJ_ALREADY_EXIST      The listener is already set.
 608          * @exception  E_SYSTEM         A system error has occurred.
 609          *
 610          */
 611         result SetCheckpointEventListener(IAppCheckpointEventListener& listener);
 612
 613         /**
 614          * @if OSPDEPREC
 615          * Sends the result list for the application control request. @n
 616          * The client can get the result list by implementing IAppControlEventListener::OnAppControlCompleted().
 617          *
 618          * @brief       <i> [Deprecated] </i>
 619          * @deprecated  This method is deprecated because a new method has been added. @n
 620          *                      Instead of using this method, use AppControlProviderManager::SendAppControlResult().
 621          * @since               2.0
 622          *
 623          * @return              An error code
 624          * @param[in]   appControlRequestId     The application control request ID @n
 625          *                          The application control request ID is given as an argument for
 626          *                          App::GetAppArgumentListN() or App::OnUserEventReceivedN().
 627          * @param[in]   pResultList     The list of the result strings of the application control
 628          * @exception   E_SUCCESS                               The method is successful.
 629          * @exception   E_OBJ_NOT_FOUND                 The application control request is not found.
 630          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 631          * @exception   E_SYSTEM                                A system error has occurred.
 632          * @see IAppControlEventListener
 633          * @endif
 634          */
 635         static result SendAppControlResult(const Tizen::Base::String& appControlRequestId, const Tizen::Base::Collection::IList* pResultList);
 636
 637         /**
 638      * Sets an IAppLaunchConditionEventListener to the %AppManager. @n
 639      * The listener gets notified when the application is launched by the registered condition.
 640      *
 641      * @since   2.0
 642          *
 643      * @param[in]  pListener      The event listener @n
 644      *                            To unset the listener, pass a @c null value to the listener parameter.
 645      * @remarks    If the application is newly launched by the condition, then %SetAppLaunchConditionEventListener() must
 646      *             be set within App::OnAppInitializing().
 647      *             If the application does not set the listener using %SetAppLaunchConditionEventListener(),
 648      *             then the application is launched without invoking any listener for the condition.
 649      * @see RegisterAppLaunch()
 650      */
 651         void SetAppLaunchConditionEventListener(IAppLaunchConditionEventListener* pListener);
 652
 653         /**
 654          * Adds an IActiveAppEventListener to the %AppManager. @n
 655          * The listener gets notified when the active application is changed.
 656          *
 657          * @since       2.0
 658          *
 659          * @privlevel   partner
 660          * @privilege   %http://tizen.org/privilege/appusage
 661          *
 662          * @return              An error code
 663          * @param[in]   listener                                The event listener
 664          * @exception   E_SUCCESS                               The method is successful.
 665          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 666          * @exception   E_OBJ_ALREADY_EXIST             The listener is already added.
 667          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 668          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 669          * @remarks             Active application is the top most window with focus.
 670          * @see                 GetActiveApp()
 671          * @see                 RemoveActiveAppEventListener()
 672          */
 673         result AddActiveAppEventListener(IActiveAppEventListener& listener);
 674
 675         /**
 676          * Removes an IActiveAppEventListener from the %AppManager.
 677          *
 678          * @since       2.0
 679          *
 680          * @privlevel   partner
 681          * @privilege   %http://tizen.org/privilege/appusage
 682          *
 683          * @return              An error code
 684          * @param[in]   listener                                The event listener
 685          * @exception   E_SUCCESS                               The method is successful.
 686          * @exception   E_OBJ_NOT_FOUND                 The specified @c listener is not found.
 687          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 688          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 689          * @see                 GetActiveApp()
 690          * @see                 AddActiveAppEventListener()
 691          */
 692         result RemoveActiveAppEventListener(IActiveAppEventListener& listener);
 693
 694         /**
 695          * Gets the current active application AppId.
 696          *
 697          * @since       2.0
 698          *
 699          * @privlevel   partner
 700          * @privilege   %http://tizen.org/privilege/appusage
 701          *
 702          * @return              An error code
 703          * @param[out]  appId                                   The AppId of the active application
 704          * @exception   E_SUCCESS                               The method is successful.
 705          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 706          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 707          * @remarks             Active application is the top most window with focus.
 708          * @see                 AddActiveAppEventListener()
 709          * @see                 RemoveActiveAppEventListener()
 710          */
 711         result GetActiveApp(AppId& appId);
 712
 713         /**
 714          * Checks whether the specified application is declared as preferred application for any AppControl resolution
 715          *
 716          * @since         2.2
 717          * @privlevel      platform
 718          * @privilege     %http://tizen.org/privilege/appmanager.setting
 719          *
 720          * @return        @c true if the application is running, @n
 721          *           else @c false
 722          * @param[in]    appId                         Application ID
 723          * @exception    E_SUCCESS                   The method is successful.
 724          * @exception    E_SYSTEM                    The method cannot proceed due to a severe system error.
 725          * @exception    E_APP_NOT_INSTALLED    The specified application is not installed.
 726          * @exception    E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 727          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 728          * @remarks      For more information on AppControl resolution, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_controls.htm">Application Controls</a>.
 729          */
 730         bool IsUserPreferredAppForAppControlResolution(const AppId& appId) const;
 731
 732         /**
 733          * Clear user preference for all AppControl resolutions on the specified application.
 734          *
 735          * @since         2.2
 736          * @privlevel      platform
 737          * @privilege     %http://tizen.org/privilege/appmanager.setting
 738          *
 739          * @return        An error code
 740          * @param[in]    appId                         The preferred application's ID
 741          * @exception    E_SUCCESS                   The method is successful.
 742          * @exception    E_SYSTEM                    The method cannot proceed due to a severe system error.
 743          * @exception    E_APP_NOT_INSTALLED    The specified application is not installed.
 744          * @exception    E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 745          * @remarks      For more information on AppControl resolution, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_controls.htm">Application Controls</a>.
 746          */
 747         result ClearUserPreferenceForAppControlResolution(const AppId& appId);
 748
 749 private:
 750         /**
 751          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 752          *
 753          * @since       2.0
 754          */
 755         AppManager(void);
 756
 757         /**
 758          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 759          *
 760          * @since       2.0
 761          */
 762         AppManager(const AppManager& rhs);
 763
 764         /**
 765          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 766          *
 767          * @since       2.0
 768          */
 769         AppManager& operator =(const AppManager& rhs);
 770
 771         /**
 772          * Constructs the instance of this class.
 773          *
 774          * @since       2.0
 775          *
 776          * @return          An error code
 777          * @exception   E_SUCCESS       The method is successful.
 778          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 779          * @exception   E_SYSTEM                        A system error has occurred.
 780          */
 781         result Construct(void);
 782
 783         /**
 784          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 785          *
 786          * @since       2.0
 787          */
 788         virtual ~AppManager(void);
 789
 790 private:
 791         class _AppManagerImpl* __pAppManagerImpl;
 792
 793         friend class _AppManagerImpl;
 794 }; // AppManager
 795
 796 }} // Tizen::App
 797
 798 #endif // _FAPP_APP_MANAGER_H_
 799