inc/FAppAppManager.h

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