Merge "Fix memory leak on imei" into tizen_2.2
[platform/framework/native/appfw.git] / inc / FAppApp.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        FAppApp.h
19  * @brief       This is the header file for the %App class.
20  *
21  * This header file contains the declarations of the %App class.
22  */
23
24 #ifndef _FAPP_APP_H_
25 #define _FAPP_APP_H_
26
27 #include <FAppTypes.h>
28 #include <FSysBattery.h>
29
30 extern "C" {
31 int _OSP_EXPORT_ main(int argc, char* pArgv[]);
32 };
33
34 namespace Tizen { namespace Base { namespace Collection { class IList; } } }
35
36 namespace Tizen { namespace App
37 {
38
39 class AppRegistry;
40 class AppResource;
41
42 /**
43  * @class       App
44  * @brief       This class is the base class of a %Tizen native application.
45  *
46  * @since       2.0
47  *
48  * The %App class is the base class of a %Tizen native application.
49  * A %Tizen native application must be inherited from the UiApp or ServiceApp class. These classes are inherited from the %App class. This class provides the basic features necessary to define an application.
50  * @n
51  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_namespace.htm">App Guide</a>, <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/tizen_app_model/application_lifecycle.htm">Application Life-cycle</a>, and <a href="../org.tizen.native.appprogramming/html/guide/app/app_system_events.htm">System Events</a>.
52  *
53  */
54 class _OSP_EXPORT_ App
55         : public Tizen::Base::Object
56 {
57 public:
58         /**
59          * This destructor overrides Tizen::Base::Object::~Object().
60          *
61          * @since       2.0
62          */
63         virtual ~App(void);
64
65         /**
66          * Gets an instance of AppRegistry that manages the application's states and preferences.
67          *
68          * @since       2.0
69          *
70          * @return      A pointer to the AppRegistry instance, @n
71          *                      else @c null if it fails
72          */
73         AppRegistry* GetAppRegistry(void) const;
74
75         /**
76         * Gets an instance of AppResource that manages the application's resources.
77         *
78         * @since        2.0
79         *
80         * @return       A pointer to the AppResource instance, @n
81         *                   else @c null if it fails
82         */
83         AppResource* GetAppResource(void) const;
84
85         /**
86          * @if OSPDEPREC
87          * Gets the list of the launch arguments. @n
88          * For more information on the launch arguments, see <a href="../org.tizen.native.appprogramming/html/guide/app/launching_other_apps_within_apps.htm">Launching Other Applications</a>.
89          *
90          * @brief       <i> [Deprecated] </i>
91          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use IAppControlProviderEventListener
92          *                      to acquire delivered arguments list.
93          * @since       2.0
94          *
95          * @return      A pointer to the list that contains the Tizen::Base::String instances of the launch arguments
96          * @see AppManager::LaunchApplication()
97          * @see AppManager::RegisterAppLaunch()
98          * @see AppManager::StartAppControl()
99          * @see AppControl::Start()
100          * @endif
101          */
102         Tizen::Base::Collection::IList* GetAppArgumentListN(void) const;
103
104         /**
105          * Gets the current state of the application.
106          *
107          * @since       2.0
108          *
109          * @return      The current state of the application
110          */
111         AppState GetAppState(void) const;
112
113         /**
114          * Gets the locale-independent name of the application.
115          *
116          * @if OSPCOMPAT
117          * @brief <i> [Compatibility] </i>
118          * @endif
119          * @since       2.0
120          * @if OSPCOMPAT
121          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
122          *                                      For more information, see @ref CompGetAppNamePage "here".
123          * @endif
124          * @return      The name of the application
125          */
126         Tizen::Base::String GetAppName(void) const;
127
128         /**
129          * @page        CompGetAppNamePage Compatibility for GetAppName()
130          * @section     CompGetAppNamePageIssue Issues
131          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
132          *
133          * -# GetAppName() returns the localized name of the application while the meaning of the application name is ambiguous.
134          *  There are different use cases for locale-dependent name and localized name and the platform does not provide
135          *  a method for obtaining language-neutral name.
136          *
137          * @section     CompGetAppNamePageResolution Resolutions
138          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
139          *
140          * -# GetAppDisplayName() is introduced to acquire localized name and GetAppName() returns locale-independent application name.
141          */
142
143         /**
144          * Gets the display name of the application. @n
145          * If the system language setting is changed, the %GetAppDisplayName() method returns the localized application name.
146          * The display name is displayed in applications like Launcher, Setting, Task Switcher, and so on.
147          *
148          * @since       2.0
149          *
150          * @return      The display name of the application
151          */
152         Tizen::Base::String GetAppDisplayName(void) const;
153
154         /**
155          * Gets the version of the application.
156          *
157          * @since       2.0
158          *
159          * @return      The version of the application
160          */
161         Tizen::Base::String GetAppVersion(void) const;
162
163         /**
164          * Gets the application ID.
165          *
166          * @since       2.0
167          *
168          * @return      The application ID
169          */
170         AppId GetAppId(void) const;
171
172         /**
173         * Gets the path of the application's root directory where the application is installed.
174         *
175         * @since        2.0
176         *
177         * @return       The application's root directory path
178         */
179         Tizen::Base::String GetAppRootPath(void) const;
180
181         /**
182         * Gets the path of the application's data directory used to store its own private data.
183         *
184         * @since        2.0
185         *
186         * @return       The application's data directory path
187         */
188         Tizen::Base::String GetAppDataPath(void) const;
189
190         /**
191         * Gets the path of the application's resource directory that ships resource files delivered with the application
192         * package.
193         *
194         * @since        2.0
195         *
196         * @return       The application's resource directory path
197         */
198         Tizen::Base::String GetAppResourcePath(void) const;
199
200         /**
201         * Gets the path of the application's shared directory to export data to other applications.
202         *
203         * @since        2.1
204         *
205         * @return       The application's shared directory path
206         */
207         Tizen::Base::String GetAppSharedPath(void) const;
208
209         /**
210          * Terminates the application while it is running. @n
211          * The %Terminate() method can be called explicitly by the application. The OnAppTerminating() method is called after this method is executed successfully.
212          *
213          * @since       2.0
214          *
215          * @return      An error code
216          * @exception   E_SUCCESS           The method is successful.
217          * @exception   E_INVALID_STATE     This instance is in an invalid state.
218          */
219         result Terminate(void);
220
221         /**
222          * Called when the application's state changes to App::INITIALIZING. @n
223          * In general, most of the activities involved in initializing the application,
224          * including restoring the application's states, must be done in the %OnAppInitializing() method.
225          * If this method fails, the application's state changes to App::TERMINATED.
226          *
227          * @since       2.0
228          *
229          * @return      @c true if the method is successful, @n
230          *              else @c false
231          * @param[in]   appRegistry        The instance of AppRegistry that manages the application's states
232          * @remarks     Introducing the modal dialogs (for example, MessageBox) in this method is not allowed,
233          * because it blocks the initialization procedure.
234          */
235         virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
236
237         /**
238          * Called when the application's initialization is finished. @n
239          * After the %OnAppInitialized() method succeeds, the application's state changes to App::RUNNING.
240          * If this method fails, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
241          *
242          * @since       2.0
243          *
244          * @return      @c true if the method is successful, @n
245          *                      else @c false
246          */
247         virtual bool OnAppInitialized(void);
248
249         /**
250          * Called when the application is requested to terminate. @n
251          * The %OnAppWillTerminate() method returns @c false to prevent the application from getting terminated.
252          * If this method returns @c true, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
253          *
254          * @since       2.0
255          *
256          * @return      @c true if the method is successful, @n
257          *                      else @c false
258          */
259         virtual bool OnAppWillTerminate(void);
260
261         /**
262          * Called when the application's state changes to App::TERMINATING. @n
263          * All the activities involved in terminating the application, including saving the application's states, must be done in the %OnAppTerminating() method.
264          * After this method, the application code cannot be executed. The application is destroyed subsequently. @n
265          *
266          * An application's termination is triggered either by the system or other applications. @n
267          * When the termination is triggered by the system because of conditions such as power-off and OOM, it is called "urgent termination" and during these terminations %OnAppTerminating(), cannot be executed properly.
268          * When an application is terminated because of a power-off, although this method is called, it should be executed in a short duration. And when an application is killed by OOM, this method is not called. @n
269          * This implies that this method is not likely to be called during an urgent termination, and hence the application should save the critical data as often as possible.
270          * For example, the application can set a check point or use the callback for low memory.
271          * When an application is terminated by self or other applications, it is called "normal termination" and during these terminations this method is executed properly because more time is provided for executing it as compared to an urgent termination (however, it does have a limit of 3-5 seconds). @n
272          * When this method is called, the main loop has already been quit.
273          * Thus, the application should not use any kind of asynchronous API that has callbacks triggered by the main loop.
274          *
275          * @since       2.0
276          *
277          * @return      @c true if the method is successful, @n
278          *                      else @c false
279          * @param[in]   appRegistry         The instance that manages the application's states
280          * @param[in]   urgentTermination   Set to @c true if the application is terminated by the system, @n
281          *                                                                      else @c false
282          */
283         virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
284
285         /**
286          * Called when the system detects that the system wide memory or application heap memory is insufficient to run the application any further. @n
287          * Resources that are not in use currently can be released using the %OnLowMemory() method.
288          *
289          * @since       2.0
290          */
291         virtual void OnLowMemory(void);
292
293         /**
294          * Called when the battery level changes. @n
295          * It is recommended that the application decides whether to terminate by itself by considering its own battery power consumption, if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
296          *
297          * @since       2.0
298          *
299          * @param[in]   batteryLevel    The device's current battery level
300          */
301         virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
302
303         /**
304         * Sends the user event to the application itself and not to another application.
305         *
306         * @since        2.0
307         *
308         * @return               An error code
309         * @param[in]    requestId   The user defined event ID
310         * @param[in]    pArgs       A pointer to an argument list of type Tizen::Base::String
311         * @exception    E_SUCCESS   The method is successful.
312         * @see                  OnUserEventReceivedN()
313         */
314         result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
315
316         /**
317         * Called asynchronously when the user event is sent by the SendUserEvent() method.
318         *
319         * @since        2.0
320         *
321         * @param[in]    requestId   The user defined event ID
322         * @param[in]    pArgs       A pointer to an argument list of type Tizen::Base::String
323         */
324         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
325
326         /**
327         * Gets the %App instance's pointer.
328         *
329         * @since        2.0
330         *
331         * @return       A pointer to the %App instance, @n
332         *                       else @c null if it fails
333         */
334         static App* GetInstance(void);
335
336 protected:
337         /**
338          * This is the default constructor for this class.
339          *
340          * @since       2.0
341          */
342         App(void);
343
344         //
345         // This method is for internal use only.
346         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
347         //
348         // This method is reserved and may change its name at any time without prior notice.
349         //
350         // @since       2.0
351         //
352         virtual void App_Reserved1(void) {}
353
354         //
355         // This method is for internal use only.
356         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
357         //
358         // This method is reserved and may change its name at any time without prior notice.
359         //
360         // @since       2.0
361         //
362         virtual void App_Reserved2(void) {}
363
364 private:
365         /**
366          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
367          *
368          * @since       2.0
369          */
370         App(const App& rhs);
371
372         /**
373          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
374          *
375          * @since       2.0
376          */
377         App& operator =(const App& rhs);
378
379 private:
380         class _AppImpl* __pAppImpl;
381 }; // App
382
383 }} // Tizen::App
384
385 #endif // _FAPP_APP_H_