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  *
  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 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 the 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          * -# 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.
 136          *
 137          * @section     CompGetAppNamePageResolution Resolutions
 138          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
 139          *
 140          * -# The GetAppDisplayName() method is introduced to acquire the localized application name and the GetAppName() method returns the 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 to 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 to the application's data directory where its private data is stored.
 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 to the application's resource directory that ships the resource files that are delivered with the application package.
 192         *
 193         * @since        2.0
 194         *
 195         * @return       The application's resource directory path
 196         */
 197         Tizen::Base::String GetAppResourcePath(void) const;
 198
 199         /**
 200         * Gets the path to the application's shared directory to export data to other applications.
 201         *
 202         * @since        2.1
 203         *
 204         * @return       The application's shared directory path
 205         */
 206         Tizen::Base::String GetAppSharedPath(void) const;
 207
 208         /**
 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.
 211          *
 212          * @since       2.0
 213          *
 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.
 217          */
 218         result Terminate(void);
 219
 220         /**
 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.
 225          *
 226          * @since               2.0
 227          *
 228          * @return              @c true if the method is successful, @n
 229          *                              else @c false
 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.
 233          */
 234         virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
 235
 236         /**
 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.
 240          *
 241          * @since       2.0
 242          *
 243          * @return      @c true if the method is successful, @n
 244          *                      else @c false
 245          */
 246         virtual bool OnAppInitialized(void);
 247
 248         /**
 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.
 252          *
 253          * @since       2.0
 254          *
 255          * @return      @c true if the method is successful, @n
 256          *                      else @c false
 257          */
 258         virtual bool OnAppWillTerminate(void);
 259
 260         /**
 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
 264          *
 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.
 273          *
 274          * @since       2.0
 275          *
 276          * @return              @c true if the method is successful, @n
 277          *                              else @c false
 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
 280          *                                                                      else @c false
 281          */
 282         virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
 283
 284         /**
 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.
 287          *
 288          * @since       2.0
 289          */
 290         virtual void OnLowMemory(void);
 291
 292         /**
 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.
 295          *
 296          * @since       2.0
 297          *
 298          * @param[in]   batteryLevel    The device's current battery level
 299          */
 300         virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
 301
 302         /**
 303         * Sends the user event to the application itself and not to another application.
 304         *
 305         * @since        2.0
 306         *
 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()
 312         */
 313         result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 314
 315         /**
 316         * Called asynchronously when the user event is sent by the SendUserEvent() method.
 317         *
 318         * @since        2.0
 319         *
 320         * @param[in]    requestId   The user defined event ID
 321         * @param[in]    pArgs       A pointer to the argument list of type Tizen::Base::String
 322         */
 323         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 324
 325         /**
 326         * Gets a pointer to the %App instance.
 327         *
 328         * @since        2.0
 329         *
 330         * @return       A pointer to the %App instance, @n
 331         *                       else @c null if it fails
 332         */
 333         static App* GetInstance(void);
 334
 335 protected:
 336         /**
 337          * This is the default constructor for this class.
 338          *
 339          * @since       2.0
 340          */
 341         App(void);
 342
 343         //
 344         // This method is for internal use only.
 345         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 346         //
 347         // This method is reserved and may change its name at any time without prior notice.
 348         //
 349         // @since       2.0
 350         //
 351         virtual void App_Reserved1(void) {}
 352
 353         //
 354         // This method is for internal use only.
 355         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 356         //
 357         // This method is reserved and may change its name at any time without prior notice.
 358         //
 359         // @since       2.0
 360         //
 361         virtual void App_Reserved2(void) {}
 362
 363 private:
 364         /**
 365          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 366          *
 367          * @since       2.0
 368          */
 369         App(const App& rhs);
 370
 371         /**
 372          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 373          *
 374          * @since       2.0
 375          */
 376         App& operator =(const App& rhs);
 377
 378 private:
 379         class _AppImpl* __pAppImpl;
 380 }; // App
 381
 382 }} // Tizen::App
 383
 384 #endif // _FAPP_APP_H_