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 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>.
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.
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 * -# 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.
137 * @section CompGetAppNamePageResolution Resolutions
138 * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
140 * -# GetAppDisplayName() is introduced to acquire localized name and GetAppName() returns 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 of 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 of the application's data directory used to store its own private data.
186 * @return The application's data directory path
188 Tizen::Base::String GetAppDataPath(void) const;
191 * Gets the path of the application's resource directory that ships resource files delivered with the application
196 * @return The application's resource directory path
198 Tizen::Base::String GetAppResourcePath(void) const;
201 * Gets the path of the application's shared directory to export data to other applications.
205 * @return The application's shared directory path
207 Tizen::Base::String GetAppSharedPath(void) const;
210 * Terminates the application while it is running. @n
211 * The OnAppTerminating() method is called after the %Terminate() method is executed successfully.
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.
219 result Terminate(void);
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.
229 * @return @c true if the method is successful, @n
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.
235 virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
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.
244 * @return @c true if the method is successful, @n
247 virtual bool OnAppInitialized(void);
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.
256 * @return @c true if the method is successful, @n
259 virtual bool OnAppWillTerminate(void);
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
266 * An application can be terminated either by system, such as power-off and OOM, or others, such as self and other applications. @n
267 * When the termination by system, called an “urgent termination”, occurs, the method, %OnAppTerminating(), cannot be executed properly.
268 * For more details, while power-off, even if %OnAppTerminating() is called, it has a short time for executing. If the application is killed by OOM, %OnAppTerminating() is not called. @n
269 * Because %OnAppTerminating() is not likely to be called due to urgent termination, the application should save the critical data as they can do.
270 * For example, the application can set the check point or use the callback for low memory. @n
271 * When the termination by self or other applications, called a “normal termination”, occurs, the method, %OnAppTerminating(), can be executed properly.
272 * It provides more time for executing than urgent termination, but limits to the time to 3 or 5 seconds. @n
273 * The main loop is already quitted when %OnAppTerminating() is called.
274 * Thus, the application should not use a kind of asynchronous API of which the callback is triggered by the main loop.
278 * @return @c true if the method is successful, @n
280 * @param[in] appRegistry The instance that manages the application's states
281 * @param[in] urgentTermination Set to @c true if the application is terminated by the system, @n
284 virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
287 * Called when the system detects that the system wide memory or application heap memory is insufficient to run the application any further. @n
288 * Resources that are not in use currently can be released using the %OnLowMemory() method.
292 virtual void OnLowMemory(void);
295 * Called when the battery level changes. @n
296 * It is recommended that the application consuming more battery power must be terminated if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
300 * @param[in] batteryLevel The device's current battery level
302 virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
305 * Sends the user event to the application itself and not to another application.
309 * @return An error code
310 * @param[in] requestId The user defined event ID
311 * @param[in] pArgs A pointer to an argument list of type Tizen::Base::String
312 * @exception E_SUCCESS The method is successful.
313 * @see OnUserEventReceivedN()
315 result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
318 * Called asynchronously when the user event is sent by the SendUserEvent() method. @n
319 * The request ID and argument format for the user event can be defined as per the requirement.
323 * @param[in] requestId The user defined event ID
324 * @param[in] pArgs A pointer to an argument list of type Tizen::Base::String
326 virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
329 * Gets the %App instance's pointer.
333 * @return A pointer to the %App instance, @n
334 * else @c null if it fails
336 static App* GetInstance(void);
340 * This is the default constructor for this class.
347 // This method is for internal use only.
348 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
350 // This method is reserved and may change its name at any time without prior notice.
354 virtual void App_Reserved1(void) {}
357 // This method is for internal use only.
358 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
360 // This method is reserved and may change its name at any time without prior notice.
364 virtual void App_Reserved2(void) {}
368 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
375 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
379 App& operator =(const App& rhs);
382 class _AppImpl* __pAppImpl;
387 #endif // _FAPP_APP_H_