inc/engine/base/Timer.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 #ifndef HERE_TIMER_H
  18 #define HERE_TIMER_H
  19
  20 #include <glib.h>
  21
  22 #include "common/HereMaps_global.h"
  23 #include "base/BaseObject.h"
  24
  25 TIZEN_MAPS_BEGIN_NAMESPACE
  26
  27 class Timer;
  28
  29 enum TimerStatus
  30 {
  31         TIMER_STATUS_NOT_ACTIVATED, // This enum value is for internal use only. Using this enum can cause behavioral, security-related, and consistency-related issues in the application.
  32         TIMER_STATUS_ACTIVATED,     // This enum value is for internal use only. Using this enum can cause behavioral, security-related, and consistency-related issues in the application.
  33         TIMER_STATUS_CANCELED,      // This enum value is for internal use only. Using this enum can cause behavioral, security-related, and consistency-related issues in the application.
  34         TIMER_STATUS_EXPIRED,       // This enum value is for internal use only. Using this enum can cause behavioral, security-related, and consistency-related issues in the application.
  35         TIMER_STATUS_ACTIVATED_REPEATABLE,       // This enum value is for internal use only. Using this enum can cause behavioral, security-related, and consistency-related issues in the application.
  36 };
  37
  38 class ITimerEventListener
  39 {
  40 public:
  41         /**
  42          * This is the destructor for this class.
  43          *
  44          * @since 2.0
  45          */
  46         virtual ~ITimerEventListener(void) {}
  47
  48         /**
  49          *      Called when the timer has expired.
  50          *
  51          *  @since 2.0
  52          *
  53          *      @param[in]      timer   The expired timer
  54          */
  55         virtual void OnTimerExpired(Timer& timer) = 0;
  56
  57 }; // ITimerEventListener
  58
  59 class Timer : public Object
  60 {
  61 public:
  62         /**
  63          * This is the default constructor for this class.
  64          *
  65          * @since 2.0
  66          */
  67         Timer(void);
  68
  69
  70         /**
  71          * This is the destructor for this class.
  72          *
  73          * @since 2.0
  74          */
  75         virtual ~Timer(void);
  76
  77         /**
  78          * Initializes this instance of %Timer with the specified listener.
  79          *
  80          * @since 2.0
  81          *
  82          * @return              An error code
  83          * @param[in]   listener                The event listener
  84          * @exception   E_SUCCESS               The method is successful.
  85          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
  86          * @exception   E_SYSTEM                A system error has occurred.
  87          */
  88         int Construct(ITimerEventListener& listener);
  89
  90         /**
  91          * Starts the timer.
  92          *
  93          * @if OSPCOMPAT
  94          * @brief <i> [Compatibility] </i>
  95          * @endif
  96          *
  97          * @since 2.0
  98          *
  99          * @if OSPCOMPAT
 100      * @compatibility     This method has compatibility issues with Tizen API versions @b prior @b to @b 2.1. @n
 101      *                    For more information, see @ref CompTimerStartPage "here".
 102          * @endif
 103          *
 104          * @return      An error code
 105          * @param[in]   timeout                 The timeout interval in milliseconds
 106          * @exception   E_SUCCESS                       The method is successful.
 107          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 108          * @exception   E_INVALID_STATE         The timer cannot start as it is in an invalid state.
 109          * @exception   E_SYSTEM                        A system error has occurred.
 110          * @remarks     Once the timer has been started, it cannot be started again until it has expired.
 111          * @see         Cancel()
 112          */
 113         int Start(int timeout);
 114
 115         /**
 116          * @page                    CompTimerStartPage Compatibility for Start(int timeout)
 117          * @section                 CompTimerStartPageIssueSection Issues
 118          * Implementation of this method in Tizen API versions prior to 2.1 has the following issue: @n
 119          * -# The method returns @c E_INVALID_ARG if timeout is equal to zero.
 120          *
 121          * @section                 CompTimerStartPageSolutionSection Resolutions
 122          * The issue mentioned above is resolved in Tizen API version 2.1, and it is recommended to use Tizen API version 2.1 or above.
 123          * -# In case of zero, %Timer sets the timeout to the best possible minimum interval without returning @c E_INVALID_ARG.
 124          */
 125
 126         /**
 127          * Starts the timer. @n
 128          * The timer expires repeatedly until it is cancelled.
 129          *
 130          * @since 2.0
 131          *
 132          * @return      An error code
 133          * @param[in]   interval                        The timeout interval in milliseconds
 134          * @exception   E_SUCCESS                       The method is successful.
 135          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 136          * @exception   E_INVALID_STATE The timer cannot start as it is in an invalid state.
 137          * @exception   E_SYSTEM                        A system error has occurred.
 138          * @remarks     To stop the timer expiration or restart the timer, the timer must be cancelled.
 139          * @see         Cancel()
 140          */
 141         int StartAsRepeatable(int interval);
 142
 143         /**
 144          * Cancels the timer.
 145          *
 146          * @since 2.0
 147          *
 148          * @return              An error code
 149          * @exception   E_SUCCESS       The method is successful.
 150          * @exception   E_SYSTEM        A system error has occurred.
 151          * @remarks     The started timer can be cancelled when it does not get expired. @n
 152          *                      If the timer has already expired, this method also returns @c E_SUCCESS which causes the same effect as when cancelled normally.
 153          */
 154         int Cancel(void);
 155
 156 private:
 157         Timer(const Timer& rhs);
 158
 159         Timer& operator =(const Timer& rhs);
 160
 161 private:
 162         friend class _TimerImpl;
 163         class _TimerImpl * __pTimerImpl;
 164
 165 }; // Timer
 166
 167 TIZEN_MAPS_END_NAMESPACE
 168
 169 #endif /* HERE_TIMER_H */