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 Manager, 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 OnAppTerminating() method is called after the %Terminate() 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 can be terminated by either 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.
 275          *
 276          * @since       2.0
 277          *
 278          * @return      @c true if the method is successful, @n
 279          *                      else @c false
 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
 282          *                                                                      else @c false
 283          */
 284         virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
 285
 286         /**
 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.
 289          *
 290          * @since       2.0
 291          */
 292         virtual void OnLowMemory(void);
 293
 294         /**
 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.
 297          *
 298          * @since       2.0
 299          *
 300          * @param[in]   batteryLevel    The device's current battery level
 301          */
 302         virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
 303
 304         /**
 305         * Sends the user event to the application itself and not to another application.
 306         *
 307         * @since        2.0
 308         *
 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()
 314         */
 315         result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 316
 317         /**
 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.
 320         *
 321         * @since        2.0
 322         *
 323         * @param[in]    requestId   The user defined event ID
 324         * @param[in]    pArgs       A pointer to an argument list of type Tizen::Base::String
 325         */
 326         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 327
 328         /**
 329         * Gets the %App instance's pointer.
 330         *
 331         * @since        2.0
 332         *
 333         * @return       A pointer to the %App instance, @n
 334         *                       else @c null if it fails
 335         */
 336         static App* GetInstance(void);
 337
 338 protected:
 339         /**
 340          * This is the default constructor for this class.
 341          *
 342          * @since       2.0
 343          */
 344         App(void);
 345
 346         //
 347         // This method is for internal use only.
 348         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 349         //
 350         // This method is reserved and may change its name at any time without prior notice.
 351         //
 352         // @since       2.0
 353         //
 354         virtual void App_Reserved1(void) {}
 355
 356         //
 357         // This method is for internal use only.
 358         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 359         //
 360         // This method is reserved and may change its name at any time without prior notice.
 361         //
 362         // @since       2.0
 363         //
 364         virtual void App_Reserved2(void) {}
 365
 366 private:
 367         /**
 368          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 369          *
 370          * @since       2.0
 371          */
 372         App(const App& rhs);
 373
 374         /**
 375          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 376          *
 377          * @since       2.0
 378          */
 379         App& operator =(const App& rhs);
 380
 381 private:
 382         class _AppImpl* __pAppImpl;
 383 }; // App
 384
 385 }} // Tizen::App
 386
 387 #endif // _FAPP_APP_H_