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_