inc/FAppApp.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file        FAppApp.h
  20  * @brief       This is the header file for the %App class.
  21  *
  22  * This header file contains the declarations of the %App class.
  23  */
  24
  25 #ifndef _FAPP_APP_H_
  26 #define _FAPP_APP_H_
  27
  28 #include <FAppTypes.h>
  29 #include <FSysBattery.h>
  30
  31 extern "C" {
  32 int _OSP_EXPORT_ main(int argc, char* pArgv[]);
  33 };
  34
  35 namespace Tizen { namespace Base { namespace Collection { class IList; } } }
  36
  37 namespace Tizen { namespace App
  38 {
  39
  40 class AppRegistry;
  41 class AppResource;
  42
  43 /**
  44  * @class       App
  45  * @brief       This class is the base class of a Tizen native application.
  46  *
  47  * @since       2.0
  48  *
  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.
  51  * @n
  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>.
  53  *
  54  */
  55 class _OSP_EXPORT_ App
  56         : public Tizen::Base::Object
  57 {
  58 public:
  59         /**
  60          * This destructor overrides Tizen::Base::Object::~Object().
  61          *
  62          * @since       2.0
  63          */
  64         virtual ~App(void);
  65
  66         /**
  67          * Gets an instance of AppRegistry that manages the application's states and preferences.
  68          *
  69          * @since       2.0
  70          *
  71          * @return      A pointer to the AppRegistry instance, @n
  72          *                      else @c null if it fails
  73          */
  74         AppRegistry* GetAppRegistry(void) const;
  75
  76         /**
  77         * Gets an instance of AppResource that manages the application's resources.
  78         *
  79         * @since        2.0
  80         *
  81         * @return       A pointer to the AppResource instance, @n
  82         *                   else @c null if it fails
  83         */
  84         AppResource* GetAppResource(void) const;
  85
  86         /**
  87          * @if OSPDEPREC
  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>.
  90          *
  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.
  94          * @since       2.0
  95          *
  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()
 101          * @endif
 102          */
 103         Tizen::Base::Collection::IList* GetAppArgumentListN(void) const;
 104
 105         /**
 106          * Gets the current state of the application.
 107          *
 108          * @since       2.0
 109          *
 110          * @return      The current state of the application
 111          */
 112         AppState GetAppState(void) const;
 113
 114         /**
 115          * Gets the locale-independent name of the application.
 116          *
 117          * @if OSPCOMPAT
 118          * @brief <i> [Compatibility] </i>
 119          * @endif
 120          * @since       2.0
 121          * @if OSPCOMPAT
 122          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 123          *                                      For more information, see @ref CompGetAppNamePage "here".
 124          * @endif
 125          * @return      The name of the application
 126          */
 127         Tizen::Base::String GetAppName(void) const;
 128
 129         /**
 130          * @page        CompGetAppNamePage Compatibility for GetAppName()
 131          * @section     CompGetAppNamePageIssue Issues
 132          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
 133          *
 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.
 137          *
 138          * @section     CompGetAppNamePageResolution Resolutions
 139          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
 140          *
 141          * -# GetAppDisplayName() is introduced to acquire localized name and GetAppName() returns locale-independent application name.
 142          */
 143
 144         /**
 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.
 148          *
 149          * @since       2.0
 150          *
 151          * @return      The display name of the application
 152          */
 153         Tizen::Base::String GetAppDisplayName(void) const;
 154
 155         /**
 156          * Gets the version of the application.
 157          *
 158          * @since       2.0
 159          *
 160          * @return      The version of the application
 161          */
 162         Tizen::Base::String GetAppVersion(void) const;
 163
 164         /**
 165          * Gets the application ID.
 166          *
 167          * @since       2.0
 168          *
 169          * @return      The application ID
 170          */
 171         AppId GetAppId(void) const;
 172
 173         /**
 174         * Gets the path of the application's root directory where the application is installed.
 175         *
 176         * @since        2.0
 177         *
 178         * @return       The application's root directory path
 179         */
 180         Tizen::Base::String GetAppRootPath(void) const;
 181
 182         /**
 183         * Gets the path of the application's data directory used to store its own private data.
 184         *
 185         * @since        2.0
 186         *
 187         * @return       The application's data directory path
 188         */
 189         Tizen::Base::String GetAppDataPath(void) const;
 190
 191         /**
 192         * Gets the path of the application's resource directory that ships resource files delivered with the application
 193         * package.
 194         *
 195         * @since        2.0
 196         *
 197         * @return       The application's resource directory path
 198         */
 199         Tizen::Base::String GetAppResourcePath(void) const;
 200
 201         /**
 202         * Gets the path of the application's shared directory to export data to other applications.
 203         *
 204         * @since        2.1
 205         *
 206         * @return       The application's shared directory path
 207         */
 208         Tizen::Base::String GetAppSharedPath(void) const;
 209
 210         /**
 211          * Terminates the application while it is running. @n
 212          * The OnAppTerminating() method is called after the %Terminate() method is executed successfully.
 213          *
 214          * @since       2.0
 215          *
 216          * @return      An error code
 217          * @exception   E_SUCCESS           The method is successful.
 218          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 219          */
 220         result Terminate(void);
 221
 222         /**
 223          * Called when the application's state changes to App::INITIALIZING. @n
 224          * In general, most of the activities involved in initializing the application,
 225          * including restoring the application's states, must be done in the %OnAppInitializing() method.
 226          * If this method fails, the application's state changes to App::TERMINATED.
 227          *
 228          * @since       2.0
 229          *
 230          * @return      @c true if the method is successful, @n
 231          *              else @c false
 232          * @param[in]   appRegistry        The instance of AppRegistry that manages the application's states
 233          * @remarks     Introducing the modal dialogs (for example, MessageBox) in this method is not allowed,
 234          * because it blocks the initialization procedure.
 235          */
 236         virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
 237
 238         /**
 239          * Called when the application's initialization is finished. @n
 240          * After the %OnAppInitialized() method succeeds, the application's state changes to App::RUNNING.
 241          * If this method fails, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
 242          *
 243          * @since       2.0
 244          *
 245          * @return      @c true if the method is successful, @n
 246          *                      else @c false
 247          */
 248         virtual bool OnAppInitialized(void);
 249
 250         /**
 251          * Called when the application is requested to terminate. @n
 252          * The %OnAppWillTerminate() method returns @c false to prevent the application from getting terminated.
 253          * If this method returns @c true, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
 254          *
 255          * @since       2.0
 256          *
 257          * @return      @c true if the method is successful, @n
 258          *                      else @c false
 259          */
 260         virtual bool OnAppWillTerminate(void);
 261
 262         /**
 263          * Called when the application's state changes to App::TERMINATING. @n
 264          * All the activities involved in terminating the application, including saving the application's states, must be done in the %OnAppTerminating() method.
 265          * After this method, the application code cannot be executed. The application is destroyed subsequently. @n
 266          *
 267          * An application can be terminated by either system, such as power-off and OOM, or others, such as self and other applications. @n
 268          * When the termination by system, called an “urgent termination”, occurs, the method, OnAppTerminating(), cannot be executed properly.
 269          * 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
 270          * Because OnAppTerminating() is not likely to be called due to urgent termination, the application should save the critical data as they can do.
 271          * For example, the application can set the check point or use the callback for low memory. @n
 272          * When the termination by self or other applications, called a “normal termination”, occurs, the method, OnAppTerminating(), can be executed properly.
 273          * It provides more time for executing than urgent termination, but limits to the time to 3 or 5 seconds. @n
 274          * The main loop is already quitted when OnAppTerminating() is called.
 275          * Thus, the application should not use a kind of asynchronous API of which the callback is triggered by the main loop.
 276          *
 277          * @since       2.0
 278          *
 279          * @return      @c true if the method is successful, @n
 280          *                      else @c false
 281          * @param[in]   appRegistry         The instance that manages the application's states
 282          * @param[in]   urgentTermination   Set to @c true if the application is terminated by the system, @n
 283          *                                                                      else @c false
 284          */
 285         virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
 286
 287         /**
 288          * Called when the system detects that the system wide memory or application heap memory is insufficient to run the application any further. @n
 289          * Resources that are not in use currently can be released using the %OnLowMemory() method.
 290          *
 291          * @since       2.0
 292          */
 293         virtual void OnLowMemory(void);
 294
 295         /**
 296          * Called when the battery level changes. @n
 297          * It is recommended that the application consuming more battery power must be terminated if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
 298          *
 299          * @since       2.0
 300          *
 301          * @param[in]   batteryLevel    The device's current battery level
 302          */
 303         virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
 304
 305         /**
 306         * Sends the user event to the application itself and not to another application.
 307         *
 308         * @since        2.0
 309         *
 310         * @return               An error code
 311         * @param[in]    requestId   The user defined event ID
 312         * @param[in]    pArgs       A pointer to an argument list of type Tizen::Base::String
 313         * @exception    E_SUCCESS   The method is successful.
 314         * @see                  OnUserEventReceivedN()
 315         */
 316         result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 317
 318         /**
 319         * Called asynchronously when the user event is sent by the SendUserEvent() method. @n
 320         * The request ID and argument format for the user event can be defined as per the requirement.
 321         *
 322         * @since        2.0
 323         *
 324         * @param[in]    requestId   The user defined event ID
 325         * @param[in]    pArgs       A pointer to an argument list of type Tizen::Base::String
 326         */
 327         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 328
 329         /**
 330         * Gets the %App instance's pointer.
 331         *
 332         * @since        2.0
 333         *
 334         * @return       A pointer to the %App instance, @n
 335         *                       else @c null if it fails
 336         */
 337         static App* GetInstance(void);
 338
 339 protected:
 340         /**
 341          * This is the default constructor for this class.
 342          *
 343          * @since       2.0
 344          */
 345         App(void);
 346
 347         //
 348         // This method is for internal use only.
 349         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 350         //
 351         // This method is reserved and may change its name at any time without prior notice.
 352         //
 353         // @since       2.0
 354         //
 355         virtual void App_Reserved1(void) {}
 356
 357         //
 358         // This method is for internal use only.
 359         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 360         //
 361         // This method is reserved and may change its name at any time without prior notice.
 362         //
 363         // @since       2.0
 364         //
 365         virtual void App_Reserved2(void) {}
 366
 367 private:
 368         /**
 369          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 370          *
 371          * @since       2.0
 372          */
 373         App(const App& rhs);
 374
 375         /**
 376          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 377          *
 378          * @since       2.0
 379          */
 380         App& operator =(const App& rhs);
 381
 382 private:
 383         class _AppImpl* __pAppImpl;
 384 }; // App
 385
 386 }} // Tizen::App
 387
 388 #endif // _FAPP_APP_H_