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  *
  43  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/timer.htm">Timer</a>.
  44  *
  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  */
 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 OSP compatibile applications. @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         * Implementing this method in OSP compatible applications has the following issues:   @n
 178         * -# The method returns E_INVALID_ARG if timeout is equal to zero.
 179         *
 180         * @section                 CompTimerStartPageSolutionSection Resolutions
 181         * This issue has been resolved in Tizen.  @n
 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_