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         *                       - If the platform policy is changed or the device is different, the returned file path can be different. @n
 267         *                         Rather than changing the returned file path as hard coding, use as it is.
 268         */
 269         static Tizen::Base::String GetAppSharedPath(const AppId& appId);
 270
 271         /**
 272          * Gets a pointer to the %AppManager instance.
 273          *
 274          * @since       2.0
 275          *
 276          * @return      A pointer to the %AppManager instance, @n
 277          *                      else @c null if it fails
 278          */
 279         static AppManager* GetInstance(void);
 280
 281         /**
 282          * @if OSPDEPREC
 283          * Launches the default application with the given @c appId. @n
 284          * The launch arguments are given by the App::OnUserEventReceivedN() method or can be obtained by
 285          * invoking the App::GetAppArgumentListN() method, especially within App::OnAppInitializing().
 286          *
 287          * @brief               <i> [Deprecated] </i>
 288          * @deprecated  This method is deprecated because sending arguments through the %LaunchApplication() method is not recommended. @n
 289          *                              Instead of using this method, use the %LaunchApplication() method without launch arguments or AppControl::Start().
 290          * @since               2.0
 291          * @privlevel   public
 292          * @privilege   %http://tizen.org/privilege/application.launch
 293          *
 294          * @return              An error code
 295          * @param[in]   appId                           The ID of the application to execute
 296          * @param[in]   pArguments                      A pointer to the list of string arguments that has a maximum size of @c 1024 bytes
 297          * @param[in]   option                          The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 298          * @exception   E_SUCCESS                       The method is successful.
 299          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 300          * @exception   E_INVALID_ARG           The specified @c appId is empty.
 301          * @exception   E_OBJ_NOT_FOUND         The target application has not been installed.
 302          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 303          * @exception   E_MAX_EXCEEDED          The size of @c appId or @c pArguments has exceeded the maximum limit.
 304          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 305          * @exception E_ILLEGAL_ACCESS          The application is not signed with the same certificate as that of the target application. @b Since: @b 2.1
 306          * @endif
 307          */
 308         result LaunchApplication(const AppId& appId, const Tizen::Base::Collection::IList* pArguments, LaunchOption option = LAUNCH_OPTION_DEFAULT);
 309
 310         /**
 311          * Launches the default application with the given @c appId.
 312          *
 313          * @since               2.0
 314          * @privlevel   public
 315          * @privilege   %http://tizen.org/privilege/application.launch
 316          *
 317          * @return              An error code
 318          * @param[in]   appId                           The ID of the application to execute
 319          * @param[in]   option                          The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 320          * @exception   E_SUCCESS                       The method is successful.
 321          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 322          * @exception   E_APP_NOT_INSTALLED     The target application has not been installed.
 323          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 324          * @exception E_ILLEGAL_ACCESS          The application is not signed with the same certificate as that of the target application. @b Since: @b 2.1
 325          */
 326         result LaunchApplication(const AppId& appId, LaunchOption option = LAUNCH_OPTION_DEFAULT);
 327
 328         /**
 329          * Terminates an application.
 330          *
 331          * @since       2.0
 332          * @privlevel   partner
 333          * @privilege   %http://tizen.org/privilege/appmanager.kill @n
 334          *                              (%http://tizen.org/privilege/application.kill is deprecated.)
 335          *
 336          * @return              An error code
 337          * @param[in]   appId                           The ID of the application to execute
 338          * @exception   E_SUCCESS                       The method is successful.
 339          * @exception   E_SYSTEM                        A system error has occurred.
 340          * @exception   E_OBJ_NOT_FOUND         Either of the following conditions has occurred:
 341          *                                                              - The application is not installed.
 342          *                                                              - The application is not running.
 343          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 344          */
 345         result TerminateApplication(const AppId& appId);
 346
 347         /**
 348          * Checks whether the application is running.
 349          *
 350          * @since       2.0
 351          *
 352          * @return              @c true if the application is running, @n
 353          *              else @c false
 354          * @param[in]   appId               The installed application's ID
 355          */
 356         bool IsRunning(const AppId& appId) const;
 357
 358         /**
 359          * Gets the list of running applications at the time of the invocation.
 360          *
 361          * @since      2.0
 362          *
 363          * @return              A pointer to the running state application list (AppId), @n
 364          *              else @c null if an error occurs
 365          * @exception   E_SUCCESS                       The method is successful.
 366          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 367          * @exception   E_SYSTEM                        A system error has occurred.
 368          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 369          */
 370         Tizen::Base::Collection::IList* GetRunningAppListN(void) const;
 371
 372         /**
 373          * Registers an application with a specific condition and launches it if the condition is met. @n
 374          * If the requested application is already running, the application is notified through the IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 375          * The launch arguments are given as input parameters to the %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 376          *
 377          * @since               2.0
 378          * @privlevel   public
 379          * @privilege   %http://tizen.org/privilege/application.launch
 380          * @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
 381          *
 382          * @return              An error code
 383          * @param[in]   condition         The launch condition for the application @n
 384          *                                        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
 385          *                                        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>.
 386          *                                        <table><tr><th>Condition Format</th><th>Meaning</th></tr>
 387          *                                        <tr><td>L"DateTime='mm/dd/yyyy hh:mm:ss'"</td>
 388          *                                        <td>The specified condition is the local due time.</td></tr>
 389          *                                        <tr><td>L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'"</td>
 390          *                                        <td>The specified condition is the time period after the due time.</td></tr>
 391          *                                        <tr><td>L"WeeklyTime='EEE HH:mm:ss'"</td>
 392          *                                        <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>
 393          *                                        <tr><td>L"Serial='command'"</td><td>The specified condition is a serial
 394          *                                        communication input command.</td></tr>
 395          *                                        <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.
 396          *                                        </td></tr></table> @n
 397          *
 398          *
 399          * @param[in]   pArguments                              The list of string arguments that has a maximum size of @c 1024 bytes @n
 400          *                                                                      This parameter can also contain @c null. @n
 401          *                                                                      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>.
 402          * @param[in]   option                                  The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 403          * @exception   E_SUCCESS                               The method is successful.
 404          * @exception   E_INVALID_ARG                   The launch condition is empty or too long (Maximum 400 bytes).
 405          * @exception   E_INVALID_FORMAT                  The specified condition format is invalid.
 406          * @exception   E_INVALID_CONDITION       The specified condition format is valid but the condition has at least one or more invalid values.
 407          * @exception   E_OBJ_ALREADY_EXIST               The specified @c condition is already registered by a different application.
 408          * @exception   E_OUT_OF_MEMORY                   The memory is insufficient.
 409          * @exception   E_MAX_EXCEEDED                    The size of @c pArguments has exceeded the maximum limit.
 410          * @exception   E_SYSTEM                                  A system error has occurred.
 411          * @exception   E_PRIVILEGE_DENIED                The application does not have the privilege to call this method.
 412          * @exception   E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature.
 413          *                                                                        For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>. @b Since: @b 2.1
 414          *
 415          * @remarks
 416          *                      - When the registered application is about to be launched, the registered launch condition and arguments are given as parameters to the
 417          *                      IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 418          *                      - For the NFC launch condition, the detected NDEF message can be acquired using the @c pExtraData parameter of the
 419          *                      %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 420          *                      - The newly introduced launch condition does not work on the previous SDK version and @c E_INVALID_CONDITION is returned.
 421          *                      - Registering the same launch condition overwrites the previous launch argument without throwing an exception.
 422          *                      - The launch period requires more consideration because an inappropriate short period value may lead to an adverse effect on the device battery.
 423          *                      - Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 424          * @see                 UnregisterAppLaunch()
 425          * @see                 IsAppLaunchRegistered()
 426          * @see                 LaunchApplication(const AppId&, LaunchOption);
 427          * @see                 Tizen::Base::DateTime::ToString()
 428          * @see                 Tizen::Io::SerialPort
 429          *
 430          * The following example demonstrates how to use the %RegisterAppLaunch() method.
 431          *
 432          * @code
 433          *
 434          *  DateTime time;
 435          *  SystemTime::GetCurrentTime(TIME_MODE_WALL, time);
 436          *  time.AddMinutes(1);
 437          *
 438          *  String cond;
 439          *  cond.Format(70, L"DueTime='%S' LaunchPeriod='60'", time.ToString().GetPointer());
 440          *
 441          *  // Registers a periodic condition that fires every 60 minutes starting after one minute
 442          *  AppManager::GetInstance()->RegisterAppLaunch(cond, null, AppManager::LAUNCH_OPTION_DEFAULT)
 443          *
 444          * @endcode
 445          */
 446         result RegisterAppLaunch(const Tizen::Base::String& condition, const Tizen::Base::Collection::IList* pArguments, LaunchOption option);
 447
 448         /**
 449          * Unregisters the previously registered launch condition.
 450          *
 451          * @since               2.0
 452          * @privlevel   public
 453          * @privilege   %http://tizen.org/privilege/application.launch
 454          *
 455          * @return              An error code
 456          * @exception   E_SUCCESS                               Either of the following conditions has occurred:
 457          *                                                                      - The method is successful.
 458          *                                                                      - There is no registered launch condition.
 459          * @exception   E_SYSTEM                                A system error has occurred.
 460          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 461          * @see                 RegisterAppLaunch()
 462          * @see                 IsAppLaunchRegistered()
 463          */
 464         result UnregisterAppLaunch(void);
 465
 466         /**
 467          * Unregisters the specified launch condition.
 468          *
 469          * @since               2.0
 470          * @privlevel   public
 471          * @privilege   %http://tizen.org/privilege/application.launch
 472          *
 473          * @return              An error code
 474          * @param[in]   condition                       The launch condition for the application
 475          * @exception   E_SUCCESS                       The method is successful.
 476          * @exception   E_OBJ_NOT_FOUND         The specified launch condition has not been found.
 477          * @exception   E_SYSTEM                        A system error has occurred.
 478          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 479          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 480          * @see                 RegisterAppLaunch()
 481          * @see                 IsAppLaunchRegistered()
 482          */
 483         result UnregisterAppLaunch(const Tizen::Base::String& condition);
 484
 485         /**
 486          * Checks whether the launch condition is registered for the application.
 487          *
 488          * @since       2.0
 489          *
 490          * @return     @c true if the condition is already registered for the application, @n
 491          *             else @c false
 492          * @exception  E_SUCCESS                        The method is successful.
 493          * @exception  E_SYSTEM                         A system error has occurred.
 494          *
 495          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 496          * @see         RegisterAppLaunch()
 497          * @see         UnregisterAppLaunch()
 498          */
 499         bool IsAppLaunchRegistered(void) const;
 500
 501         /**
 502          * Registers the specified application with the specified condition and launches it if the condition is met. @n
 503          * If the requested application is already running, the application is notified through the IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 504          * The launch arguments are given as input parameters to the %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 505          *
 506          * @since               2.0
 507          * @privlevel   partner
 508          * @privilege   %http://tizen.org/privilege/appmanager.launch
 509          * @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
 510          *
 511          * @return     An error code
 512          * @param[in]  appId          The ID of the application registered for launch
 513          * @param[in]  condition      The launch condition for the application @n
 514          *                                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
 515          *                                                        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>.
 516          *                            <table><tr><th>Condition Format</th><th>Meaning</th></tr>
 517          *                            <tr><td>L"DateTime='mm/dd/yyyy hh:mm:ss'"</td>
 518          *                            <td>The specified condition is the local due time.</td></tr>
 519          *                            <tr><td>L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'"</td>
 520          *                            <td>The specified condition is the time period after the due time.</td></tr>
 521          *                            <tr><td>L"WeeklyTime='EEE HH:mm:ss'"</td>
 522          *                            <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>
 523          *                            <tr><td>L"Serial='command'"</td><td>The specified condition is a serial
 524          *                            communication input command.</td></tr>
 525          *                            <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.
 526          *                            </td></tr></table> @n
 527      *
 528          *
 529          * @param[in]  pArguments                                  The list of string arguments that has a maximum size of @c 1024 bytes @n
 530          *                                                                                 The parameter can also contain @c null. @n
 531          *                                                                         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>.
 532          * @param[in]  option                              The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available)
 533          * @exception  E_SUCCESS                                   The method is successful.
 534          * @exception  E_APP_NOT_INSTALLED                 The application has not been installed.
 535          * @exception  E_INVALID_ARG                       The launch condition is empty or too long (Maximum 400 bytes).
 536          * @exception  E_INVALID_FORMAT                    The specified condition format is invalid.
 537          * @exception  E_INVALID_CONDITION         The specified condition format is valid but the condition has at least one or more invalid values.
 538          * @exception  E_OUT_OF_MEMORY                     The memory is insufficient.
 539          * @exception  E_MAX_EXCEEDED                      The size of @c pArguments has exceeded the maximum limit.
 540          * @exception  E_SYSTEM                                    A system error has occurred.
 541          * @exception  E_PRIVILEGE_DENIED                  The application does not have the privilege to call this method.
 542          * @exception  E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature.
 543          *                                                                                 For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>. @b Since: @b 2.1
 544          *
 545          * @remarks
 546          *                      - When the registered application is about to be launched, the registered launch condition and arguments are given as parameters to the
 547          *                      IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 548          *                      - For the NFC launch condition, the detected NDEF message can be acquired using the @c pExtraData parameter of the
 549          *                      %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method.
 550          *                      - The newly introduced launch condition does not work on the previous SDK version and @c E_INVALID_CONDITION is returned.
 551          *                      - Registering the same launch condition overwrites the previous launch argument without throwing an exception.
 552          *                      - The launch period requires more consideration because an inappropriate short period value may lead
 553          *                      to an adverse effect on the device battery.
 554          *                      - Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 555          * @see        UnregisterAppLaunch()
 556          * @see        IsAppLaunchRegistered()
 557          * @see        LaunchApplication(const AppId&, LaunchOption);
 558          * @see        Tizen::Base::DateTime::ToString()
 559          * @see        Tizen::Io::SerialPort
 560          */
 561         result RegisterAppLaunch(const AppId& appId, const Tizen::Base::String& condition, const Tizen::Base::Collection::IList* pArguments, LaunchOption option);
 562
 563         /**
 564          * Unregisters the launch condition.
 565          *
 566          * @since               2.0
 567          * @privlevel   partner
 568          * @privilege   %http://tizen.org/privilege/appmanager.launch
 569          *
 570          * @return     An error code
 571          * @param[in]  appId                    The application ID
 572          * @param[in]  pCondition           The launch condition to unregister @n
 573          *                                  If the parameter contains @c null, all the conditions are unregistered.
 574          * @exception  E_SUCCESS                        The method is successful.
 575          * @exception  E_APP_NOT_INSTALLED      The application has not been installed.
 576          * @exception  E_OBJ_NOT_FOUND          The specified launch condition has not been found.
 577          * @exception  E_SYSTEM                         A system error has occurred.
 578          * @exception  E_OUT_OF_MEMORY          The memory is insufficient.
 579          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 580          *
 581          * @see         RegisterAppLaunch()
 582          * @see         IsAppLaunchRegistered()
 583          */
 584         result UnregisterAppLaunch(const AppId& appId, const Tizen::Base::String* pCondition);
 585
 586         /**
 587          * Checks whether a previously registered launch condition is present for the specified application.
 588          *
 589          * @since               2.0
 590          * @privlevel   partner
 591          * @privilege   %http://tizen.org/privilege/appmanager.launch
 592          *
 593          * @return     @c true if the condition is already registered for the specified application with the specified condition, @n
 594          *             else @c false
 595          * @param[in]  appId                    The application ID
 596          * @param[in]  pCondition               The launch condition to register for the specified @c appId @n
 597          *                                      If the parameter contains @c null, the method checks for any registered launch condition for the specified @c appId.
 598          * @exception  E_SUCCESS                        The method is successful.
 599          * @exception  E_APP_NOT_INSTALLED      The application has not been installed.
 600          * @exception  E_SYSTEM                         A system error has occurred.
 601          * @exception  E_OUT_OF_MEMORY          The memory is insufficient.
 602          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 603          *
 604          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 605          * @see         RegisterAppLaunch()
 606          * @see         UnregisterAppLaunch()
 607          */
 608         bool IsAppLaunchRegistered(const AppId& appId, const Tizen::Base::String* pCondition = null) const;
 609
 610         /**
 611          * Sets a checkpoint event listener. @n
 612          * The listener gets notified when a checkpoint event is fired.
 613          *
 614          * @since       2.0
 615          *
 616          * @return              An error code
 617          * @param[in]   listener                        The listener to receive the checkpoint event
 618          * @exception   E_SUCCESS                       The method is successful.
 619          * @exception   E_OBJ_ALREADY_EXIST     The listener is already set.
 620          * @exception   E_SYSTEM                                A system error has occurred.
 621          *
 622          */
 623         result SetCheckpointEventListener(IAppCheckpointEventListener& listener);
 624
 625         /**
 626          * @if OSPDEPREC
 627          * Sends the result list for the application control request. @n
 628          * The client gets the result list by implementing the IAppControlEventListener::OnAppControlCompleted() method.
 629          *
 630          * @brief               <i> [Deprecated] </i>
 631          * @deprecated  This method is deprecated because a new method has been added. @n
 632          *                              Instead of using this method, use AppControlProviderManager::SendAppControlResult().
 633          * @since               2.0
 634          *
 635          * @return              An error code
 636          * @param[in]   appControlRequestId             The application control request ID @n
 637          *                                              The application control request ID is given as an argument to the
 638          *                                              App::GetAppArgumentListN() method or the App::OnUserEventReceivedN() method.
 639          * @param[in]   pResultList                             The list of the result strings of the application control
 640          * @exception   E_SUCCESS                               The method is successful.
 641          * @exception   E_OBJ_NOT_FOUND                 The application control request has not been found.
 642          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 643          * @exception   E_SYSTEM                                A system error has occurred.
 644          * @see IAppControlEventListener
 645          * @endif
 646          */
 647         static result SendAppControlResult(const Tizen::Base::String& appControlRequestId, const Tizen::Base::Collection::IList* pResultList);
 648
 649         /**
 650          * Sets an IAppLaunchConditionEventListener for the %AppManager. @n
 651          * The listener gets notified when the application is launched by the registered condition.
 652          *
 653          * @since       2.0
 654          *
 655          * @param[in]  pListener      The event listener @n
 656          *                            To unset the listener, pass a @c null value to the listener parameter.
 657          * @remarks If the application is newly launched by the condition, then the %SetAppLaunchConditionEventListener() method
 658          *                      within App::OnAppInitializing() must be set. @n
 659          *                      If the application does not set the listener using the %SetAppLaunchConditionEventListener() method,
 660          *                      then the application is launched without invoking any listener for the condition.
 661          * @see RegisterAppLaunch()
 662          */
 663         void SetAppLaunchConditionEventListener(IAppLaunchConditionEventListener* pListener);
 664
 665         /**
 666          * Adds an IActiveAppEventListener for the %AppManager. @n
 667          * The listener gets notified when the active application is changed.
 668          *
 669          * @since       2.0
 670          *
 671          * @privlevel   partner
 672          * @privilege   %http://tizen.org/privilege/appusage
 673          *
 674          * @return              An error code
 675          * @param[in]   listener                                The event listener
 676          * @exception   E_SUCCESS                               The method is successful.
 677          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 678          * @exception   E_OBJ_ALREADY_EXIST             The listener is already added.
 679          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 680          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 681          * @remarks             The active application is the top most window with focus.
 682          * @see                 GetActiveApp()
 683          * @see                 RemoveActiveAppEventListener()
 684          */
 685         result AddActiveAppEventListener(IActiveAppEventListener& listener);
 686
 687         /**
 688          * Removes an IActiveAppEventListener from the %AppManager.
 689          *
 690          * @since       2.0
 691          *
 692          * @privlevel   partner
 693          * @privilege   %http://tizen.org/privilege/appusage
 694          *
 695          * @return              An error code
 696          * @param[in]   listener                                The event listener
 697          * @exception   E_SUCCESS                               The method is successful.
 698          * @exception   E_OBJ_NOT_FOUND                 The specified @c listener has not been found.
 699          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 700          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 701          * @see                 GetActiveApp()
 702          * @see                 AddActiveAppEventListener()
 703          */
 704         result RemoveActiveAppEventListener(IActiveAppEventListener& listener);
 705
 706         /**
 707          * Gets the current active application's ID.
 708          *
 709          * @since       2.0
 710          *
 711          * @privlevel   partner
 712          * @privilege   %http://tizen.org/privilege/appusage
 713          *
 714          * @return              An error code
 715          * @param[out]  appId                                   The ID of the active application
 716          * @exception   E_SUCCESS                               The method is successful.
 717          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 718          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 719          * @remarks             The active application is the top most window with focus.
 720          * @see                 AddActiveAppEventListener()
 721          * @see                 RemoveActiveAppEventListener()
 722          */
 723         result GetActiveApp(AppId& appId);
 724
 725         /**
 726          * Checks whether the specified application is declared as the preferred application for any AppControl resolution
 727          *
 728          * @since         2.2
 729          * @privlevel     platform
 730          * @privilege     %http://tizen.org/privilege/appmanager.setting
 731          *
 732          * @return        @c true if the application is running, @n
 733          *                else @c false
 734          * @param[in]     appId                       The application ID
 735          * @exception     E_SUCCESS                   The method is successful.
 736          * @exception     E_SYSTEM                    The method cannot proceed due to a severe system error.
 737          * @exception     E_APP_NOT_INSTALLED             The specified application has not been installed.
 738          * @exception     E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 739          * @remarks
 740          *                      - The specific error code can be accessed using the GetLastResult() method.
 741          *                      - For more information on AppControl resolution, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_controls.htm">Application Controls</a>.
 742          */
 743         bool IsUserPreferredAppForAppControlResolution(const AppId& appId) const;
 744
 745         /**
 746          * Clears the user preference for all the AppControl resolutions of the specified application.
 747          *
 748          * @since         2.2
 749          * @privlevel     platform
 750          * @privilege     %http://tizen.org/privilege/appmanager.setting
 751          *
 752          * @return       An error code
 753          * @param[in]    appId                         The preferred application's ID
 754          * @exception    E_SUCCESS                     The method is successful.
 755          * @exception    E_SYSTEM                      The method cannot proceed due to a severe system error.
 756          * @exception    E_APP_NOT_INSTALLED           The specified application has not been installed.
 757          * @exception    E_PRIVILEGE_DENIED            The application does not have the privilege to call this method.
 758          * @remarks      For more information on AppControl resolution, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_controls.htm">Application Controls</a>.
 759          */
 760         result ClearUserPreferenceForAppControlResolution(const AppId& appId);
 761
 762 private:
 763         /**
 764          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 765          *
 766          * @since       2.0
 767          */
 768         AppManager(void);
 769
 770         /**
 771          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 772          *
 773          * @since       2.0
 774          */
 775         AppManager(const AppManager& rhs);
 776
 777         /**
 778          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 779          *
 780          * @since       2.0
 781          */
 782         AppManager& operator =(const AppManager& rhs);
 783
 784         /**
 785          * Constructs the instance of this class.
 786          *
 787          * @since       2.0
 788          *
 789          * @return          An error code
 790          * @exception   E_SUCCESS       The method is successful.
 791          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 792          * @exception   E_SYSTEM                        A system error has occurred.
 793          */
 794         result Construct(void);
 795
 796         /**
 797          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 798          *
 799          * @since       2.0
 800          */
 801         virtual ~AppManager(void);
 802
 803 private:
 804         class _AppManagerImpl* __pAppManagerImpl;
 805
 806         friend class _AppManagerImpl;
 807 }; // AppManager
 808
 809 }} // Tizen::App
 810
 811 #endif // _FAPP_APP_MANAGER_H_
 812