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