src/app/inc/FApp_AppImpl.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        FApp_AppImpl.h
  19  * @brief       This is the header file for the _AppImpl class.
  20  */
  21
  22 #ifndef _FAPP_INTERNAL_APP_IMPL_H_
  23 #define _FAPP_INTERNAL_APP_IMPL_H_
  24
  25 #include <app.h>
  26
  27 #include <FAppApp.h>
  28 #include <FSysBattery.h>
  29 #include <FBaseRtIEventListener.h>
  30
  31 #include "FApp_Types.h"
  32 #include "FApp_AppUserEvent.h"
  33 #include "FApp_IAppUserEventListener.h"
  34
  35 namespace Tizen { namespace Base { namespace Runtime
  36 {
  37 class IEventListener;
  38 }}}
  39
  40 namespace Tizen { namespace App { namespace Package
  41 {
  42 class PackageInfo;
  43 }}}
  44
  45 namespace Tizen { namespace App
  46 {
  47
  48 class IAppCheckpointEventListener;
  49 class ISqlDataControlProviderEventListener;
  50 class IMapDataControlProviderEventListener;
  51 class IAppControlProviderEventListener;
  52 class IAppLaunchConditionEventListener;
  53 class _AppArg;
  54 class _IAppImpl;
  55
  56 /**
  57  * @class       _AppImpl
  58  * @brief       This class is the Impl class of a App class.
  59  * @since 2.1
  60  *
  61  * This class is the Impl class of a App class.
  62  */
  63 class _OSP_EXPORT_ _AppImpl
  64         : public Tizen::Base::Object
  65         , public _IAppUserEventListener
  66         , virtual public Tizen::Base::Runtime::IEventListener
  67 {
  68 public:
  69         typedef result (_AppImpl::*AppRequestHandlerType)(service_s*, int, _AppHandler);
  70
  71         /**
  72          * Initializes this instance of _AppImpl with the specified arguments
  73          *
  74          * @since 2.1
  75          * @return      An error code
  76          * @param[in]   pArgs   A pointer to the list that contains the String instances of launch arguments
  77          * @exception   E_SUCCESS           The method is successful.
  78          * @exception   E_INVALID_STATE     This instance is in an invalid state.
  79          * @exception   E_INVALID_ARG       The specified input parameter is invalid.
  80          */
  81         result Construct(const Tizen::Base::Collection::IList* pArgs);
  82
  83         /**
  84          * Executes an application implemented by inheriting App class.
  85          * This method must be called from the UiApp or ServiceApp.
  86          *
  87          * @since 2.1
  88          * @return      An error code
  89          * @exception   E_SUCCESS           The method is successful.
  90          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
  91          * @exception   E_OUT_OF_MEMORY     Insufficient memory.
  92          * @exception   E_INIT_FAILED       The initialization failure during OnAppInitializing().
  93          * @exception   E_SYSTEM            A system error has occurred.
  94          */
  95         result Execute(_IAppImpl* pIAppImpl);
  96
  97         /**
  98         * Returns the _AppImpl's instance pointer.
  99         *
 100         * @since 2.1
 101         * @return       A pointer to the %_AppImpl instance, @n
 102         *                       else @c null if it fails
 103         */
 104         static _AppImpl* GetInstance();
 105
 106         /**
 107         * Returns the App's instance pointer.
 108         *
 109         * @since 2.1
 110         * @return       A pointer to the %App instance, @n
 111         *                       else @c null if it fails
 112         */
 113         App* GetAppInstance();
 114
 115         /**
 116          * Returns the status of the termination request
 117          *
 118          * @since 2.1
 119          * @return      @c true if the termination is requested, @n
 120          *              else @c false
 121          */
 122         static bool IsTerminationRequested(void);
 123
 124         /**
 125          * Called when the application is started
 126          *
 127          * @since 2.1
 128          * @return      @c true if the method is successful, @n
 129          *              else @c false
 130          * @param[in]   user_data       The user data passed from the callback registration function
 131          * @remarks     This is a system dependent callback function
 132          */
 133         static bool OnCreate(void* user_data);
 134
 135         /**
 136          * Called when other application send the launch request to the application
 137          *
 138          * @since 2.1
 139          * @param[in]   service The handle to the service
 140          * @param[in]   user_data       The user data passed from the callback registration function
 141          * @remarks     This is a system dependent callback function
 142          */
 143         static void OnService(service_s* service, void* user_data);
 144
 145         /**
 146          * Called when the application is completely obscured by another application and becomes invisible
 147          *
 148          * @since 2.1
 149          * @param[in]   user_data       The user data passed from the callback registration function
 150          * @remarks     This is a system dependent callback function
 151          */
 152         static void OnPause(void* user_data);
 153
 154         /**
 155          * Called when the application becomes visible
 156          *
 157          * @since 2.1
 158          * @param[in]   user_data       The user data passed from the callback registration function
 159          * @remarks     This is a system dependent callback function
 160          */
 161         static void OnResume(void* user_data);
 162
 163         /**
 164          * Called once after the main loop of application exits
 165          *
 166          * @since 2.1
 167          * @param[in]   user_data       The user data passed from the callback registration function
 168          * @remarks     This is a system dependent callback function
 169          */
 170         static void OnTerminate(void* user_data);
 171
 172         /**
 173          * Called when the system memory is running low
 174          *
 175          * @since 2.1
 176          * @param[in]   user_data       The user data passed from the callback registration function
 177          * @remarks     This is a system dependent callback function
 178          */
 179         static void OnLowMemory(void* user_data);
 180
 181         /**
 182          * Called when language setting changes
 183          *
 184          * @since 2.1
 185          * @param[in]   user_data       The user data passed from the callback registration function
 186          * @remarks     This is a system dependent callback function
 187          */
 188         static void OnLanguageChanged(void* user_data);
 189
 190         /**
 191          * Called when region format setting changes
 192          *
 193          * @since 2.1
 194          * @param[in]   user_data       The user data passed from the callback registration function
 195          * @remarks     This is a system dependent callback function
 196          */
 197         static void OnRegionFormatChanged(void* user_data);
 198
 199         /**
 200          * Set Listener
 201          *
 202          * @since 2.1
 203          * @return      An error code
 204          * @param[in]   appEvent        _AppEvent event type
 205          * @param[in]   pListener       Listener to set
 206          * @exception   E_SUCCESS           The method is successful.
 207          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 208          */
 209         result SetListener(_AppEvent appEvent, Tizen::Base::Runtime::IEventListener* pListener);
 210
 211         result SetSqlDataControlProviderEventListener(ISqlDataControlProviderEventListener* pListener);
 212
 213         result SetMapDataControlProviderEventListener(IMapDataControlProviderEventListener* pListener);
 214
 215         result SetAppControlProviderEventListener(IAppControlProviderEventListener* pListener);
 216
 217         result SetAppControlProviderInternalEventListener(IAppControlProviderEventListener* pListener);
 218
 219         result SetAppLaunchConditionEventListener(IAppLaunchConditionEventListener* pListener);
 220
 221         /**
 222          * Called when the application's initialization is finished. @n
 223          * After this method succeeds, the application's state changes to Tizen::App::AppState::RUNNING.
 224          * If the method fails, the application's state changes to Tizen::App::AppState::TERMINATING and call OnAppTerminating() subsequently.
 225          *
 226          * @since 2.1
 227          * @return      @c true if the method is successful, @n
 228          *                      else @c false
 229          */
 230         bool OnAppInitialized(void);
 231
 232         /**
 233         * Called when a checkpoint event occurs
 234         *
 235         * @since 2.1
 236         */
 237         void OnAppCheckpoint(void);
 238
 239         /**
 240          * Registers app request
 241          *
 242          * @since 2.1
 243          * @return      An error code
 244          * @param[in]   service service handle
 245          * @param[out]  req     request number
 246          * @param[out]  reason  launch reason
 247          * @exception   E_SUCCESS       The method is successful.
 248          */
 249         result RegisterAppRequest(service_s* service, int& req, _AppHandler& reason);
 250
 251         /**
 252          * Gets the window handle if exists.
 253          *
 254          * @since 2.1
 255          */
 256         long GetWindowHandle(void) const;
 257
 258
 259         void OnBatteryLevelChanged(Tizen::System::BatteryLevel batteryLevel);
 260
 261         bool IsForcedTermination(void);
 262
 263         static void OnPowerOffNotiReceived(void* pData);
 264
 265 private:
 266         /**
 267          * This is the default constructor for this class.
 268          *
 269          * @since 2.1
 270          */
 271         _AppImpl(void);
 272
 273         /**
 274          * This is the constructor for this class.
 275          *
 276          * @since 2.1
 277          */
 278         _AppImpl(App* pApp);
 279
 280         /**
 281          * This is the copy constructor for the this class.
 282          */
 283         _AppImpl(const _AppImpl& value);
 284
 285         /**
 286          * This is the assignment operator for this class.
 287          */
 288         _AppImpl& operator =(const _AppImpl& source);
 289
 290         /**
 291          * This is the destructor for this class.
 292          *
 293          * @since 2.1
 294          */
 295         virtual ~_AppImpl(void);
 296
 297         /**
 298          * Gets the list of the launch arguments. @n
 299          *
 300          * @since 2.1
 301          * @return      A pointer to the list that contains the String instances of launch arguments
 302          */
 303         Tizen::Base::Collection::IList* GetAppArgumentListN(void) const;
 304
 305         /**
 306          * Terminates the application while it is running. @n
 307          * The OnAppTerminating() method is called after this method is executed successfully.
 308          *
 309          * @since 2.1
 310          * @return      An error code
 311          * @exception   E_SUCCESS           The method is successful.
 312          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 313          */
 314         result Terminate(void);
 315
 316         /**
 317          * Calles the application's initialization routine. @n
 318          * After this method succeeds, the application's state changes to Tizen::App::AppState::RUNNING.
 319          * If the method fails, the application's state changes to Tizen::App::AppState::TERMINATING and call OnAppTerminating() subsequently.
 320          *
 321          * @since 2.1
 322          * @return      @c true if the method is successful, @n
 323          *              else @c false
 324          */
 325         bool OnAppInitializing(void);
 326
 327         /**
 328          * Called when the application is requested to terminate. @n
 329          * Return @c false if you don't want your application to terminate. @n
 330          * If the method returns @c true, the application's state changes to Tizen::App::AppState::TERMINATING and call OnAppTerminating() subsequently.
 331          *
 332          * @since 2.1
 333          * @return      @c true if the method is successful, @n
 334          *                      else @c false
 335          */
 336         bool OnAppWillTerminate(void);
 337
 338         /**
 339         * Sends the user event to the application itself and not to other application.
 340         *
 341         * @since 2.1
 342         * @return               An error code
 343         * @param[in]    requestId   The user defined event ID
 344         * @param[in]    pArgs       A pointer to an argument list of type String
 345         * @exception    E_SUCCESS   The method is successful.
 346         */
 347         result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
 348
 349         /**
 350         * Called asynchronously when the user event is sent by the SendUserEvent() method. @n
 351         * The request ID and argument format for the user event can be defined as per the requirement.
 352         *
 353         * @since 2.1
 354         * @param[in]    requestId   The user defined event ID
 355         * @param[in]    pArgs       A pointer to an argument list of type String
 356         */
 357         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 358
 359         /**
 360          * Called asynchronously when AppControl provider event is received.
 361          *
 362          * @since 2.1
 363          */
 364         void OnAppControlRequestReceived(const _AppArg& arg, RequestId reqId);
 365
 366         /**
 367          * Called asynchronously when DataControl provider event is received.
 368          *
 369          * @since 2.1
 370          * @param[in]   arg     The launch argument
 371          */
 372         void OnDataControlRequestReceived(const _AppArg& arg, RequestId reqId);
 373
 374         /**
 375          * Called asynchronously when conditional app launch event is received.
 376          *
 377          * @since 2.1
 378          */
 379         void OnConditionRequestReceived(const _AppArg& arg, RequestId reqId);
 380
 381         /**
 382          * Handles AppControl/DataControl request
 383          *
 384          * @since 2.1
 385          * @return      An error code
 386          * @exception   E_SUCCESS       The method is succesful.
 387          */
 388         result HandleAppRequest(service_s* service, int req, _AppHandler reason);
 389
 390         /**
 391          * Handles legacy UserEvent request
 392          *
 393          * @since 2.1
 394          * @return      An error code
 395          * @exception   E_SUCCESS       The method is succesful.
 396          */
 397         result HandleLegacyAppRequest(service_s* service, int req, _AppHandler reason);
 398
 399         /**
 400          * Dummy implementation for app event request
 401          *
 402          * @since 2.1
 403          * @return An error code
 404          * @exception   E_SUCCESS       The method is successful.
 405          */
 406         result HandleDummyAppRequest(service_s* service, int req, _AppHandler reason);
 407
 408         /**
 409          * Set legacy app service handler
 410          *
 411          * @since 2.1
 412          * @return An error code
 413          * @exception   E_SUCCESS       The method is successful.
 414          */
 415         result SetLegacyRequestHandler(void);
 416
 417         static bool ConfirmAppService(void);
 418
 419 private:
 420         static _AppImpl* __pAppImpl;
 421
 422         _AppUserEvent   __appUserEvent;
 423
 424         IAppCheckpointEventListener* __pCheckpointEventListener;
 425
 426         ISqlDataControlProviderEventListener* __pSqlDataControlProviderEventListener;
 427
 428         IMapDataControlProviderEventListener* __pMapDataControlProviderEventListener;
 429
 430         IAppControlProviderEventListener* __pAppControlProviderEventListener;
 431         IAppControlProviderEventListener* __pAppControlProviderInternalEventListener;
 432
 433         IAppLaunchConditionEventListener* __pAppLaunchConditionEventListener;
 434
 435         App* __pApp;
 436
 437         _IAppImpl* __pIAppImpl;
 438
 439         AppRequestHandlerType __pRequestHandler;
 440
 441         AppRequestHandlerType __pLegacyRequestHandler;
 442
 443         bool __forcedTermination;
 444
 445         static bool __isTerminationRequested;
 446
 447         friend class App;
 448 }; // _AppImpl
 449
 450 } } //Tizen::App
 451
 452 #endif // _FAPP_INTERNAL_APP_IMPL_H_