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