inc/FBaseRtTimer.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        FBaseRtTimer.h
  19  * @brief       This is the header file for the %Timer class.
  20  *
  21  * This header file contains the declarations of the %Timer class.
  22  */
  23
  24 #ifndef _FBASE_RT_TIMER_H_
  25 #define _FBASE_RT_TIMER_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseResult.h>
  29 #include <FBaseRtTypes.h>
  30 #include <FBaseRtITimerEventListener.h>
  31
  32 namespace Tizen { namespace Base { namespace Runtime
  33 {
  34 /**
  35  * @class       Timer
  36  * @brief       This class provides the timer service.
  37  *
  38  * @since 2.0
  39  *
  40  * The %Timer class can activate the timer and notify the listeners.
  41  * It supports the relative time and provides both repeatable and non-repeatable timers.
  42  * Because %Timer is handled in an event-driven way, when the main loop gets blocked, even if the time is expired, the listener cannot get notified.
  43  * Once the target goes into the sleep mode, %Timer does not work properly because the main loop gets stopped.
  44  * You can use Alarm on behalf of the %Timer for the sleep mode.
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/timer.htm">Timer</a>.
  46  * The following example demonstrates how to use the %Timer class.
  47  *
  48  * @code
  49  *
  50  *  #include <FBase.h>
  51  *
  52  *  using namespace Tizen::Base;
  53  *  using namespace Tizen::Base::Runtime;
  54  *
  55  *  class MyTimerApp
  56  *      : public ITimerEventListener
  57  *      , public Object
  58  *  {
  59  *  public:
  60  *      MyTimerApp();
  61  *      ~MyTimerApp();
  62  *
  63  *      void OnTimerExpired(Timer& timer);
  64  *      bool IsTimerExpired() const;
  65  *      int GetCount() {return __count;};
  66  *      void StartApp();
  67  *
  68  *   private:
  69  *              bool __bTimerExpired;
  70  *              int __count;
  71  *              Timer __timer;
  72  *   };
  73  *
  74  *   MyTimerApp::MyTimerApp()
  75  *      : __bTimerExpired(false)
  76  *      , __count(10)
  77  *   {
  78  *       __timer.Construct(*this);
  79  *   }
  80  *
  81  *   MyTimerApp::~MyTimerApp()
  82  *   {
  83  *   }
  84  *
  85  *   void
  86  *   MyTimerApp::OnTimerExpired(Timer& timer)
  87  *   {
  88  *       __count--;
  89  *       if (__count == 0)
  90  *       {
  91  *              __bTimerExpired = true;
  92  *       }
  93  *       else
  94  *       {
  95  *              timer.Start(100);
  96  *       }
  97  *
  98  *       AppLog("TimerApp: Current count: %d\n", __count);
  99  *   }
 100  *
 101  *   bool
 102  *   MyTimerApp::IsTimerExpired() const
 103  *   {
 104  *       return __bTimerExpired;
 105  *   }
 106  *
 107  *   void
 108  *   MyTimerApp::StartApp()
 109  *   {
 110  *       __timer.Start(10);
 111  *   }
 112  *
 113  * @endcode
 114  *
 115  * @see ITimerEventListener
 116  * @see Tizen::System::Alarm
 117  */
 118
 119 class _OSP_EXPORT_ Timer
 120         : public Tizen::Base::Object
 121 {
 122 public:
 123         /**
 124          * This is the default constructor for this class.
 125          *
 126          * @since 2.0
 127          */
 128         Timer(void);
 129
 130
 131         /**
 132          * This is the destructor for this class.
 133          *
 134          * @since 2.0
 135          */
 136         virtual ~Timer(void);
 137
 138         /**
 139          * Initializes this instance of %Timer with the specified listener.
 140          *
 141          * @since 2.0
 142          *
 143          * @return              An error code
 144          * @param[in]   listener                The event listener
 145          * @exception   E_SUCCESS               The method is successful.
 146          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 147          * @exception   E_SYSTEM                A system error has occurred.
 148          */
 149         result Construct(ITimerEventListener& listener);
 150
 151         /**
 152          * Starts the timer.
 153          *
 154          * @if OSPCOMPAT
 155          * @brief <i> [Compatibility] </i>
 156          * @endif
 157          *
 158          * @since 2.0
 159          *
 160          * @if OSPCOMPAT
 161      * @compatibility     This method has compatibility issues with Tizen API versions @b prior @b to @b 2.1. @n
 162      *                    For more information, see @ref CompTimerStartPage "here".
 163          * @endif
 164          *
 165          * @return      An error code
 166          * @param[in]   timeout                 The timeout interval in milliseconds
 167          * @exception   E_SUCCESS                       The method is successful.
 168          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 169          * @exception   E_INVALID_STATE         The timer cannot start as it is in an invalid state.
 170          * @exception   E_SYSTEM                        A system error has occurred.
 171          * @remarks     Once the timer has been started, it cannot be started again until it has expired.
 172          * @see         Cancel()
 173          */
 174         result Start(int timeout);
 175
 176         /**
 177          * @page                    CompTimerStartPage Compatibility for Start(int timeout)
 178          * @section                 CompTimerStartPageIssueSection Issues
 179          * Implementation of this method in Tizen API versions prior to 2.1 has the following issue: @n
 180          * -# The method returns @c E_INVALID_ARG if timeout is equal to zero.
 181          *
 182          * @section                 CompTimerStartPageSolutionSection Resolutions
 183          * 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.
 184          * -# In case of zero, %Timer sets the timeout to the best possible minimum interval without returning @c E_INVALID_ARG.
 185          */
 186
 187         /**
 188          * Starts the timer. @n
 189          * The timer expires repeatedly until it is cancelled.
 190          *
 191          * @since 2.0
 192          *
 193          * @return      An error code
 194          * @param[in]   interval                        The timeout interval in milliseconds
 195          * @exception   E_SUCCESS                       The method is successful.
 196          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 197          * @exception   E_INVALID_STATE The timer cannot start as it is in an invalid state.
 198          * @exception   E_SYSTEM                        A system error has occurred.
 199          * @remarks     To stop the timer expiration or restart the timer, the timer must be cancelled.
 200          * @see         Cancel()
 201          */
 202         result StartAsRepeatable(int interval);
 203
 204         /**
 205          * Cancels the timer.
 206          *
 207          * @since 2.0
 208          *
 209          * @return              An error code
 210          * @exception   E_SUCCESS       The method is successful.
 211          * @exception   E_SYSTEM        A system error has occurred.
 212          * @remarks     The started timer can be cancelled when it does not get expired. @n
 213          *                      If the timer has already expired, this method also returns @c E_SUCCESS which causes the same effect as when cancelled normally.
 214          */
 215         result Cancel(void);
 216
 217 private:
 218         Timer(const Timer& rhs);
 219
 220         Timer& operator =(const Timer& rhs);
 221
 222 private:
 223         friend class _TimerImpl;
 224         class _TimerImpl * __pTimerImpl;
 225
 226 }; // Timer
 227
 228 } } } // Tizen::Runtime
 229
 230 #endif // _FBASE_RT_TIMER_H_