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