2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
20 * @brief This is the header file for the %App class.
22 * This header file contains the declarations of the %App class.
28 #include <FAppTypes.h>
29 #include <FSysBattery.h>
32 int _OSP_EXPORT_ main(int argc, char* pArgv[]);
35 namespace Tizen { namespace Base { namespace Collection { class IList; } } }
37 namespace Tizen { namespace App
45 * @brief This class is the base class of a Tizen native application.
49 * The %App class is the base class of a %Tizen native application.
50 * 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.
52 * 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>.
55 class _OSP_EXPORT_ App
56 : public Tizen::Base::Object
60 * This destructor overrides Tizen::Base::Object::~Object().
67 * Gets an instance of AppRegistry that manages the application's states and preferences.
71 * @return A pointer to the AppRegistry instance, @n
72 * else @c null if it fails
74 AppRegistry* GetAppRegistry(void) const;
77 * Gets an instance of AppResource that manages the application's resources.
81 * @return A pointer to the AppResource instance, @n
82 * else @c null if it fails
84 AppResource* GetAppResource(void) const;
88 * Gets the list of the launch arguments. @n
89 * 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>.
91 * @brief <i> [Deprecated] </i>
92 * @deprecated This method is deprecated. Instead of using this method, it is recommended to use IAppControlProviderEventListener
93 * to acquire delivered arguments list.
96 * @return A pointer to the list that contains the Tizen::Base::String instances of the launch arguments
97 * @see AppManager::LaunchApplication()
98 * @see AppManager::RegisterAppLaunch()
99 * @see AppManager::StartAppControl()
100 * @see AppControl::Start()
103 Tizen::Base::Collection::IList* GetAppArgumentListN(void) const;
106 * Gets the current state of the application.
110 * @return The current state of the application
112 AppState GetAppState(void) const;
115 * Gets the locale-independent name of the application.
118 * @brief <i> [Compatibility] </i>
122 * @compatibility This method has compatibility issues with OSP compatible applications. @n
123 * For more information, see @ref CompGetAppNamePage "here".
125 * @return The name of the application
127 Tizen::Base::String GetAppName(void) const;
130 * @page CompGetAppNamePage Compatibility for GetAppName()
131 * @section CompGetAppNamePageIssue Issues
132 * Implementing this method in OSP compatible applications has the following issues: @n
134 * -# GetAppName() returns the localized name of the application while the meaning of the application name is ambiguous.
135 * There are different use cases for locale-dependent name and localized name and the platform does not provide
136 * a method for obtaining language-neutral name.
138 * @section CompGetAppNamePageResolution Resolutions
139 * This issue has been resolved in Tizen. @n
141 * -# GetAppDisplayName() is introduced to acquire localized name and GetAppName() returns locale-independent application name.
145 * Gets the display name of the application. @n
146 * If the system language setting is changed, the %GetAppDisplayName() method returns the localized application name.
147 * The display name is displayed in applications like Launcher, Setting, Task Manager, and so on.
151 * @return The display name of the application
153 Tizen::Base::String GetAppDisplayName(void) const;
156 * Gets the version of the application.
160 * @return The version of the application
162 Tizen::Base::String GetAppVersion(void) const;
165 * Gets the application ID.
169 * @return The application ID
171 AppId GetAppId(void) const;
174 * Gets the path of the application's root directory where the application is installed.
178 * @return The application's root directory path
180 Tizen::Base::String GetAppRootPath(void) const;
183 * Gets the path of the application's data directory used to store its own private data.
187 * @return The application's data directory path
189 Tizen::Base::String GetAppDataPath(void) const;
192 * Gets the path of the application's resource directory that ships resource files delivered with the application
197 * @return The application's resource directory path
199 Tizen::Base::String GetAppResourcePath(void) const;
202 * Terminates the application while it is running. @n
203 * The OnAppTerminating() method is called after the %Terminate() method is executed successfully.
207 * @return An error code
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_INVALID_STATE This instance is in an invalid state.
211 result Terminate(void);
214 * Called when the application's state changes to App::INITIALIZING. @n
215 * In general, most of the activities involved in initializing the application,
216 * including restoring the application's states, must be done in the %OnAppInitializing() method.
217 * If this method fails, the application's state changes to App::TERMINATED.
221 * @return @c true if the method is successful, @n
223 * @param[in] appRegistry The instance of AppRegistry that manages the application's states
224 * @remarks Introducing the modal dialogs (for example, MessageBox) in this method is not allowed,
225 * because it blocks the initialization procedure.
227 virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
230 * Called when the application's initialization is finished. @n
231 * After the %OnAppInitialized() method succeeds, the application's state changes to App::RUNNING.
232 * If this method fails, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
236 * @return @c true if the method is successful, @n
239 virtual bool OnAppInitialized(void);
242 * Called when the application is requested to terminate. @n
243 * The %OnAppWillTerminate() method returns @c false to prevent the application from getting terminated.
244 * If this method returns @c true, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
248 * @return @c true if the method is successful, @n
251 virtual bool OnAppWillTerminate(void);
254 * Called when the application's state changes to App::TERMINATING. @n
255 * All the activities involved in terminating the application, including saving the application's states, must be done in the %OnAppTerminating() method.
256 * After this method, the application code cannot be executed. The application is destroyed subsequently.
260 * @return @c true if the method is successful, @n
262 * @param[in] appRegistry The instance that manages the application's states
263 * @param[in] forcedTermination Set to @c true if the application is terminated by the system or another application, @n
266 virtual bool OnAppTerminating(AppRegistry& appRegistry, bool forcedTermination = false) = 0;
269 * Called when the system detects that the system wide memory or application heap memory is insufficient to run the application any further. @n
270 * Resources that are not in use currently can be released using the %OnLowMemory() method.
274 virtual void OnLowMemory(void);
277 * Called when the battery level changes. @n
278 * It is recommended that the application consuming more battery power must be terminated if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
282 * @param[in] batteryLevel The device's current battery level
284 virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
287 * Sends the user event to the application itself and not to another application.
291 * @return An error code
292 * @param[in] requestId The user defined event ID
293 * @param[in] pArgs A pointer to an argument list of type Tizen::Base::String
294 * @exception E_SUCCESS The method is successful.
295 * @see OnUserEventReceivedN()
297 result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
300 * Called asynchronously when the user event is sent by the SendUserEvent() method. @n
301 * The request ID and argument format for the user event can be defined as per the requirement.
305 * @param[in] requestId The user defined event ID
306 * @param[in] pArgs A pointer to an argument list of type Tizen::Base::String
308 virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
311 * Gets the %App instance's pointer.
315 * @return A pointer to the %App instance, @n
316 * else @c null if it fails
318 static App* GetInstance(void);
322 * This is the default constructor for this class.
329 // This method is for internal use only.
330 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
332 // This method is reserved and may change its name at any time without prior notice.
336 virtual void App_Reserved1(void) {}
339 // This method is for internal use only.
340 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
342 // This method is reserved and may change its name at any time without prior notice.
346 virtual void App_Reserved2(void) {}
350 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
357 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
361 App& operator =(const App& rhs);
364 class _AppImpl* __pAppImpl;
369 #endif // _FAPP_APP_H_