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