2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @brief This is the header file for the %App class.
21 * This header file contains the declarations of the %App class.
27 #include <FAppTypes.h>
28 #include <FSysBattery.h>
31 int _OSP_EXPORT_ main(int argc, char* pArgv[]);
34 namespace Tizen { namespace Base { namespace Collection { class IList; } } }
36 namespace Tizen { namespace App
44 * @brief This class is the base class of a %Tizen native application.
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.
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>.
54 class _OSP_EXPORT_ App
55 : public Tizen::Base::Object
59 * This destructor overrides Tizen::Base::Object::~Object().
66 * Gets an instance of AppRegistry that manages the application's states and preferences.
70 * @return A pointer to the AppRegistry instance, @n
71 * else @c null if it fails
73 AppRegistry* GetAppRegistry(void) const;
76 * Gets an instance of AppResource that manages the application's resources.
80 * @return A pointer to the AppResource instance, @n
81 * else @c null if it fails
83 AppResource* GetAppResource(void) const;
87 * Gets the list of 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>.
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 the delivered arguments list.
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()
102 Tizen::Base::Collection::IList* GetAppArgumentListN(void) const;
105 * Gets the current state of the application.
109 * @return The current state of the application
111 AppState GetAppState(void) const;
114 * Gets the locale-independent name of the application.
117 * @brief <i> [Compatibility] </i>
121 * @compatibility This method has compatibility issues with OSP compatible applications. @n
122 * For more information, see @ref CompGetAppNamePage "here".
124 * @return The name of the application
126 Tizen::Base::String GetAppName(void) const;
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
133 * -# The GetAppName() method returns the localized name of the application while the meaning of the application name is ambiguous.
134 * There are different use cases for the locale-dependent name and the localized name. The platform does not provide
135 * any method for obtaining the language-neutral name.
137 * @section CompGetAppNamePageResolution Resolutions
138 * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
140 * -# The GetAppDisplayName() method is introduced to acquire the localized application name and the GetAppName() method returns the locale-independent application name.
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.
150 * @return The display name of the application
152 Tizen::Base::String GetAppDisplayName(void) const;
155 * Gets the version of the application.
159 * @return The version of the application
161 Tizen::Base::String GetAppVersion(void) const;
164 * Gets the application ID.
168 * @return The application ID
170 AppId GetAppId(void) const;
173 * Gets the path to the application's root directory where the application is installed.
177 * @return The application's root directory path
179 Tizen::Base::String GetAppRootPath(void) const;
182 * Gets the path to the application's data directory where its private data is stored.
186 * @return The application's data directory path
188 Tizen::Base::String GetAppDataPath(void) const;
191 * Gets the path to the application's resource directory that ships the resource files that are delivered with the application package.
195 * @return The application's resource directory path
197 Tizen::Base::String GetAppResourcePath(void) const;
200 * Gets the path to the application's shared directory to export data to other applications.
204 * @return The application's shared directory path
206 Tizen::Base::String GetAppSharedPath(void) const;
209 * Terminates the application while it is running. @n
210 * The %Terminate() method can be called explicitly by the application. The OnAppTerminating() method is called after this method is executed successfully.
214 * @return An error code
215 * @exception E_SUCCESS The method is successful.
216 * @exception E_INVALID_STATE This instance is in an invalid state.
218 result Terminate(void);
221 * Called when the application's state changes to App::INITIALIZING. @n
222 * In general, most of the activities involved in initializing the application,
223 * including restoring the application's states, must be done in the %OnAppInitializing() method.
224 * If this method fails, the application's state changes to App::TERMINATED.
228 * @return @c true if the method is successful, @n
230 * @param[in] appRegistry The instance of AppRegistry that manages the application's states
231 * @remarks Introducing the modal dialogs (for example, MessageBox) in this method is not allowed,
232 * because it blocks the initialization procedure.
234 virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
237 * Called when the application's initialization is finished. @n
238 * After the %OnAppInitialized() method succeeds, the application's state changes to App::RUNNING.
239 * If this method fails, the application's state changes to App::TERMINATING and the OnAppTerminating() method is called.
243 * @return @c true if the method is successful, @n
246 virtual bool OnAppInitialized(void);
249 * Called when the application is requested to terminate. @n
250 * The %OnAppWillTerminate() method returns @c false to prevent the application from getting terminated.
251 * If this method returns @c true, the application's state changes to App::TERMINATING and the OnAppTerminating() method is called.
255 * @return @c true if the method is successful, @n
258 virtual bool OnAppWillTerminate(void);
261 * Called when the application's state changes to App::TERMINATING. @n
262 * All the activities involved in terminating the application, including saving the application's states, must be done by the %OnAppTerminating() method.
263 * After this method, the application code cannot be executed. The application is destroyed subsequently. @n
265 * An application's termination is triggered either by the system or by other applications. @n
266 * 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 the %OnAppTerminating() method cannot be executed properly.
267 * 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
268 * This implies that this method is not likely to be called during an urgent termination, and hence the application should save its critical data as often as possible.
269 * For example, the application can set a check point or use a callback for low memory issues.
270 * When an application terminates itself or is terminated by other applications, it is called "normal termination" and during these terminations this method is executed properly because more time is provided for execution as compared to an urgent termination (however, it does have a limit of 3-5 seconds). @n
271 * When this method is called, the main loop has already been quit.
272 * Thus, the application should not use any kind of asynchronous API that has callbacks triggered by the main loop.
276 * @return @c true if the method is successful, @n
278 * @param[in] appRegistry The instance that manages the application's states
279 * @param[in] urgentTermination Set to @c true if the application is terminated by the system, @n
282 virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
285 * Called when the system detects that the system wide memory or the application heap memory is insufficient to run the application any further. @n
286 * Resources that are not in use currently can be released using the %OnLowMemory() method.
290 virtual void OnLowMemory(void);
293 * Called when the battery level changes. @n
294 * It is recommended that the application decides whether to terminate itself by considering its own battery power consumption, if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
298 * @param[in] batteryLevel The device's current battery level
300 virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
303 * Sends the user event to the application itself and not to another application.
307 * @return An error code
308 * @param[in] requestId The user defined event ID
309 * @param[in] pArgs A pointer to the argument list of type Tizen::Base::String
310 * @exception E_SUCCESS The method is successful.
311 * @see OnUserEventReceivedN()
313 result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
316 * Called asynchronously when the user event is sent by the SendUserEvent() method.
320 * @param[in] requestId The user defined event ID
321 * @param[in] pArgs A pointer to the argument list of type Tizen::Base::String
323 virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
326 * Gets a pointer to the %App instance.
330 * @return A pointer to the %App instance, @n
331 * else @c null if it fails
333 static App* GetInstance(void);
337 * This is the default constructor for this class.
344 // This method is for internal use only.
345 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
347 // This method is reserved and may change its name at any time without prior notice.
351 virtual void App_Reserved1(void) {}
354 // This method is for internal use only.
355 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
357 // This method is reserved and may change its name at any time without prior notice.
361 virtual void App_Reserved2(void) {}
365 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
372 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
376 App& operator =(const App& rhs);
379 class _AppImpl* __pAppImpl;
384 #endif // _FAPP_APP_H_