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          * Implementing this method in OSP compatible applications has the following issues:   @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          * This issue has been resolved in Tizen.  @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          * Terminates the application while it is running. @n
 203          * The OnAppTerminating() method is called after the %Terminate() method is executed successfully.
 204          *
 205          * @since       2.0
 206          *
 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.
 210          */
 211         result Terminate(void);
 212
 213         /**
 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.
 218          *
 219          * @since       2.0
 220          *
 221          * @return      @c true if the method is successful, @n
 222          *              else @c false
 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.
 226          */
 227         virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
 228
 229         /**
 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.
 233          *
 234          * @since       2.0
 235          *
 236          * @return      @c true if the method is successful, @n
 237          *                      else @c false
 238          */
 239         virtual bool OnAppInitialized(void);
 240
 241         /**
 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.
 245          *
 246          * @since       2.0
 247          *
 248          * @return      @c true if the method is successful, @n
 249          *                      else @c false
 250          */
 251         virtual bool OnAppWillTerminate(void);
 252
 253         /**
 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.
 257          *
 258          * @since       2.0
 259          *
 260          * @return      @c true if the method is successful, @n
 261          *                      else @c false
 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
 264          *                                                                      else @c false
 265          */
 266         virtual bool OnAppTerminating(AppRegistry& appRegistry, bool forcedTermination = false) = 0;
 267
 268         /**
 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.
 271          *
 272          * @since       2.0
 273          */
 274         virtual void OnLowMemory(void);
 275
 276         /**
 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.
 279          *
 280          * @since       2.0
 281          *
 282          * @param[in]   batteryLevel    The device's current battery level
 283          */
 284         virtual void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
 285
 286         /**
 287         * Sends the user event to the application itself and not to another application.
 288         *
 289         * @since        2.0
 290         *
 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()
 296         */
 297         result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 298
 299         /**
 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.
 302         *
 303         * @since        2.0
 304         *
 305         * @param[in]    requestId   The user defined event ID
 306         * @param[in]    pArgs       A pointer to an argument list of type Tizen::Base::String
 307         */
 308         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 309
 310         /**
 311         * Gets the %App instance's pointer.
 312         *
 313         * @since        2.0
 314         *
 315         * @return       A pointer to the %App instance, @n
 316         *                       else @c null if it fails
 317         */
 318         static App* GetInstance(void);
 319
 320 protected:
 321         /**
 322          * This is the default constructor for this class.
 323          *
 324          * @since       2.0
 325          */
 326         App(void);
 327
 328         //
 329         // This method is for internal use only.
 330         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 331         //
 332         // This method is reserved and may change its name at any time without prior notice.
 333         //
 334         // @since       2.0
 335         //
 336         virtual void App_Reserved1(void) {}
 337
 338         //
 339         // This method is for internal use only.
 340         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 341         //
 342         // This method is reserved and may change its name at any time without prior notice.
 343         //
 344         // @since       2.0
 345         //
 346         virtual void App_Reserved2(void) {}
 347
 348 private:
 349         /**
 350          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 351          *
 352          * @since       2.0
 353          */
 354         App(const App& rhs);
 355
 356         /**
 357          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 358          *
 359          * @since       2.0
 360          */
 361         App& operator =(const App& rhs);
 362
 363 private:
 364         class _AppImpl* __pAppImpl;
 365 }; // App
 366
 367 }} // Tizen::App
 368
 369 #endif // _FAPP_APP_H_