1 /*

     2  * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3  * All rights reserved.

     4  * This component and the accompanying materials are made available

     5  * under the terms of "Eclipse Public License v1.0"

     6  * which accompanies this distribution, and is available

     7  * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8  *

     9  * Initial Contributors:

    10  * Nokia Corporation - initial contribution.

    11  *

    12  * Contributors:

    13  *

    14  * Description:  CFlexPeriodic class for Flexible Timer server access.

    15  *

    16  */

    17 

    18 /*

    19  * %version: 1 %

    20  */

    21 

    22 #ifndef CFLEXPERIODIC_H

    23 #define CFLEXPERIODIC_H

    24 

    25 // INCLUDE FILES

    26 #include "flextimer.h"

    27 

    28 // CLASS DECLARATION

    29 /**

    30  *  Class providing access to flexible periodic timer service.

    31  *  This class inherits CFlexTimer and provides user with a periodic

    32  *  timer very similar to CPeriodic with the exception that both

    33  *  the initial delay and the consequent intervals have flexible

    34  *  windows of opportunity during which they may expire.

    35  *  

    36  *  The flexible window sizes are set with Configure-function. If these window

    37  *  sizes are not explicitly set by the user, a default window size is used.

    38  *  See RFlexTimer for details about default window. 

    39  *  

    40  *  Note that when CFlexPeriodic expires next expiry interval always starts 

    41  *  at that moment. This means that over time, timer expiry can start to 

    42  *  "slide" when comparing to CPeriodic. 

    43  *  

    44  *  For example: CPeriodic is started at 8 o'clock with 30 minute interval.

    45  *  It will then expire at 8.30, 9.00, ... 15.30, 16.00

    46  *  

    47  *  If CFlexPeriodic is used as a timer it can possibly expire at

    48  *  8.30, 9.00, 9.28, 9.55, ... 15.45, 16.12 etc. 

    49  *

    50  *  @see CFlexTimer

    51  *  @see RFlexTimer

    52  *  @see CPeriodic

    53  *

    54  *  Example:

    55  *  

    56  *  Class definition:

    57  *  @code

    58  *  // Forward declaration

    59  *  class CFlexPeriodic;

    60  *

    61  *  // Class definition

    62  *  class CMyNetworkServiceMonitor : public CBase

    63  *      {

    64  *      public: // Members

    65  *

    66  *          // Destructor

    67  *          virtual ~CMyNetworkServiceMonitor();

    68  *

    69  *          // Two-phased constructor

    70  *          static CMyNetworkServiceMonitor* NewL(

    71  *              TTimeIntervalMicroSeconds aWindow,

    72  *              TTimeIntervalMicroSeconds aInterval );

    73  *

    74  *      private: // Members

    75  *

    76  *          // Constructor

    77  *          CMyNetworkServiceMonitor();

    78  *

    79  *          // 2nd phase constuctor

    80  *          void ConstructL(

    81  *              TTimeIntervalMicroSeconds aWindow,

    82  *              TTimeIntervalMicroSeconds aInterval );

    83  *

    84  *          // Callback function for periodic timer. A function for TCallBack.

    85  *          static TInt DoMonitoring( TAny* aArgument );

    86  *

    87  *          // Callback function for timer server errors. A function for 

    88  *          // TCallBack.

    89  *          static TInt HandleError( TAny* aArgument );

    90  *

    91  *          // Does the network server monitoring.

    92  *          // Implementation is not provided by this example.

    93  *          DoNetworkServiceMonitoring();

    94  *

    95  *      private: // Data

    96  *

    97  *          // Owns. Flexible periodic timer.

    98  *          CFlexPeriodic* iTimer;

    99  *      };

   100  *  @endcode

   101  *

   102  *  Class implementation:

   103  *  @code

   104  *  // ---------------------------------------------------------------------------

   105  *  //

   106  *  CMyNetworkServiceMonitor::CMyNetworkServiceMonitor() : iTimer( NULL )

   107  *      {

   108  *      // Nothing to do

   109  *      }

   110  *

   111  *  // ---------------------------------------------------------------------------

   112  *  //

   113  *  CMyNetworkServiceMonitor::~CMyNetworkServiceMonitor()

   114  *      {

   115  *      if ( iTimer != NULL )

   116  *          {

   117  *          iTimer->Cancel(); // Cancel pending timer

   118  *          delete iTimer;

   119  *          }

   120  *      }

   121  *

   122  *  // ---------------------------------------------------------------------------

   123  *  //

   124  *  CMyNetworkServiceMonitor* CMyNetworkServiceMonitor::NewL(

   125  *      TTimeIntervalMicroSeconds aWindow,

   126  *      TTimeIntervalMicroSeconds aInterval )

   127  *      {

   128  *      CMyNetworkServiceMonitor* self =

   129  *          new (ELeave) CMyNetworkServiceMonitor;

   130  *      CleanupStack::PushL( self );

   131  *      self->ConstructL( aWindow, aInterval );

   132  *      CleanupStack::Pop( self );

   133  *      return self;

   134  *      }

   135  *

   136  *  // ---------------------------------------------------------------------------

   137  *  //

   138  *  void CMyNetworkServiceMonitor::ConstructL(

   139  *      TTimeIntervalMicroSeconds aWindow,

   140  *      TTimeIntervalMicroSeconds aInterval )

   141  *      {

   142  *      // Constants

   143  *      const TTimeIntervalMicroSeconds KNoWindow( 0 );

   144  *      const TTimeIntervalMicroSeconds KImmediately( 0 );

   145  *

   146  *      iTimer = CFlexPeriodic::NewL( CActive::EPriorityStandard );

   147  *

   148  *      // Push timer to cleanup stack due configuration may leave

   149  *      CleanupStack::PushL( iTimer );

   150  *

   151  *      // Set delay window 0 minute

   152  *      User::LeaveIfError( 

   153  *          iTimer->Configure( KNoWindow, aWindow ) );

   154  *

   155  *      // Start the timer, 1st call immediately

   156  *      iTimer->Start(

   157  *          KImmediately,

   158  *          aInterval,

   159  *          TCallBack( DoMonitoring, this ),

   160  *          TCallBack( HandleError, this ) );

   161  *

   162  *      CleanupStack::Pop( iTimer );

   163  *      }

   164  *

   165  *  // ---------------------------------------------------------------------------

   166  *  //

   167  *  TInt CMyNetworkServiceMonitor::DoMonitoring( TAny* aArgument )

   168  *      {

   169  *      CMyNetworkServiceMonitor* monitor =

   170  *          static_cast<CMyNetworkServiceMonitor*>( aArgument );

   171  *

   172  *      monitor->DoNetworkServerMonitoring();

   173  *      return KErrNone;

   174  *      }

   175  *     

   176  *  // ---------------------------------------------------------------------------

   177  *  //

   178  *  TInt CMyNetworkServiceMonitor::HandleError( TAny* aArgument )

   179  *      {

   180  *      CMyNetworkServiceMonitor* monitor =

   181  *          static_cast<CMyNetworkServiceMonitor*>( aArgument );

   182  *

   183  *      // Handling of the timer server error (e.g. closing up the application)

   184  *      // here.

   185  *          .

   186  *          .

   187  *          .

   188  *      return KErrNone;

   189  *      }     

   190  *  @endcode

   191  */

   192 class CFlexPeriodic : public CFlexTimer

   193     {

   194 public:

   195 

   196     /**

   197      * A leaving constructor for the object.

   198      * 

   199      * @param aPriority Priority of the active object. Type CActive::TPriority

   200      * 

   201      * @return A pointer to a CFlexPeriodic object on success.

   202      * 

   203      * @leave KErrMemory Not enough memory

   204      */

   205     static IMPORT_C CFlexPeriodic* NewL( TInt aPriority );

   206 

   207     /**

   208      * Destructor for the object.

   209      */

   210     virtual IMPORT_C ~CFlexPeriodic();

   211 

   212     /**

   213      * Starts the periodic timer. After the timer has been started, it first

   214      * calls aCallBack function after the aDelay time has expired. Thereafter

   215      * the aCallBack function is called periodically after anInterval from the

   216      * previous expiry has elapsed. All the expirations happen within timing

   217      * tolerancies indicated by the flexibility windows. The flexibility

   218      * window sizes are set with a Configure-function. The Configure needs to

   219      * be called before Starting the periodic timer. 32-bit delay and interval

   220      * values.

   221 

   222      * @param aDelay is the initial delay between this Start-function and the

   223      * first timer expiry. This value presents the maximum delay - flexibility

   224      * is applied to a time window opening prior to this.

   225      * @param anInterval is the size of the intervals after the initial delay.

   226      * This value presents the maximum interval - flexibility is applied to

   227      * a time window opening prior to this. Interval must be at least one 

   228      * microsecond.

   229      * @param aCallBack is a reference to a function that is executed at each

   230      * expiry of the timer. NULL call back function reference is prohibited.

   231      * @param aCallBackError optional, but recommended parameter is a 

   232      * reference to a function that is executed if error occurs somewhere 

   233      * in FlexTimer system (e.g. memory allocation failed). 

   234      * If user does not provide this argument and error occurs, client 

   235      * is paniced. Recommended action in case of error is to hold back all 

   236      * actions for a while and give system some time to recover and free 

   237      * resources.

   238      *

   239      * @panic CFlexPeriodic  6 aDelay is negative

   240      * @panic CFlexPeriodic  7 aInterval is zero or negative

   241      * @panic CFlexPeriodic 31 aCallBack.iFunction is NULL

   242      * @panic RFlexTimer    15 Start() has been called twice without 

   243      * cancelling the timer first

   244      *

   245      * @see Configure

   246      */

   247     IMPORT_C void Start( TTimeIntervalMicroSeconds32 aDelay,

   248                          TTimeIntervalMicroSeconds32 anInterval,

   249                          TCallBack aCallBack,

   250                          TCallBack aCallBackError = TCallBack() );

   251     

   252     /**

   253      * This function overloads the Start-function with 64-bit delay and

   254      * interval values.

   255      *

   256      * @param aDelay is the initial delay between this Start-function and the

   257      * first timer expiry. This value presents the maximum delay - flexibility

   258      * is applied to a time window opening prior to this.

   259      * @param anInterval is the size of the intervals after the initial delay.

   260      * This value presents the maximum interval - flexibility is applied to

   261      * a time window opening prior to this. Interval must be at least one 

   262      * microsecond.

   263      * @param aCallBack is a reference to a function that is executed at each

   264      * expiry of the timer. NULL call back function reference is prohibited.

   265      * @param aCallBackError optional, but recommended parameter is a 

   266      * reference to a function that is executed if error occurs somewhere 

   267      * in FlexTimer system (e.g. memory allocation failed). 

   268      * If user does not provide this argument and error occurs, client 

   269      * is paniced. Recommended action in case of error is to hold back all 

   270      * actions for a while and give system some time to recover and free 

   271      * resources.

   272      *

   273      * @panic CFlexPeriodic  6 aDelay is negative

   274      * @panic CFlexPeriodic  7 aInterval is zero or negative

   275      * @panic CFlexPeriodic 31 aCallBack.iFunction is NULL

   276      * @panic RFlexTimer    15 Start() has been called twice without 

   277      * cancelling the timer first

   278      * @panic RFlexTimer    24 aDelay or aInterval is too long (over 730 days)

   279      *

   280      * @see Configure

   281      */

   282     IMPORT_C void Start( TTimeIntervalMicroSeconds aDelay,

   283                          TTimeIntervalMicroSeconds anInterval,

   284                          TCallBack aCallBack,

   285                          TCallBack aCallBackError = TCallBack() );

   286 

   287     /**

   288      * Sets the window sizes inside which the timer can expire. Must be called

   289      * before timer is started. If configure is called after the timer has

   290      * been Started, this function returns an error code.

   291      * 

   292      * The window sizes set with this function override the default window

   293      * sizes. @see RFlexTimer::Configure

   294      *

   295      * @param aDelayWindow is the flexibility window size in 32-bit

   296      * microseconds for the initial delay.

   297      * @param aIntervalWindow is the flexibility window size in 32-bit

   298      * microseconds for the intervals after the initial delay.

   299      *

   300      * @return KErrNone on success. KErrInUse, if timer has been

   301      * started already. In case of error, the window sizes not established

   302      * into the timer and need to be configured again.

   303      *

   304      * @panic CFlexPeriodic  8 aDelayWindow is negative

   305      * @panic CFlexPeriodic  9 aIntervalWindow is negative

   306      */

   307     IMPORT_C TInt Configure( TTimeIntervalMicroSeconds32 aDelayWindow,

   308                              TTimeIntervalMicroSeconds32 aIntervalWindow );

   309 

   310     /**

   311      * This function overloads the Configure-function with 64-bit parameters.

   312      *

   313      * @param aDelayWindow is the flexibility window size in 64-bit 

   314      * microseconds for the initial delay.

   315      * @param aIntervalWindow is the flexibility window size in 64-bit

   316      * microseconds for the intervals after the initial delay.

   317      *

   318      * @return KErrNone on success. KErrInUse, if timer has been

   319      * started already. In case of error, the window sizes not established

   320      * into the timer and need to be configured again.

   321      *

   322      * @panic CFlexPeriodic  8 aDelayWindow is negative

   323      * @panic CFlexPeriodic  9 aIntervalWindow is negative

   324      * @panic RFlexTimer    24 aDelayWindow or aIntervalWindow is too long 

   325      * (over 730 days)

   326      */

   327     IMPORT_C TInt Configure( TTimeIntervalMicroSeconds aDelayWindow,

   328                              TTimeIntervalMicroSeconds aIntervalWindow );

   329 

   330 protected:

   331 

   332     /**

   333      * Inherited from CActive.

   334      */

   335     virtual void RunL();

   336     

   337 private:

   338 

   339     /**

   340      * Constructs the object. The second phase of the construction.

   341      */

   342     void ConstructL();

   343 

   344     /**

   345      * Private constructor for the object.

   346      * @param aPriority The priority of the active object. If timing is

   347      * critical, it should be higher than that of all other active objects

   348      * owned by the scheduler.

   349      */

   350     CFlexPeriodic( TInt aPriority );

   351 

   352 private:

   353     

   354     /**

   355      * No definition. This function is not to be used through CFlexPeriodic.

   356      * @see CFlexTimer

   357      */

   358     void After( TTimeIntervalMicroSeconds32 aInterval );

   359     

   360     /**

   361      * No definition. This function is not to be used through CFlexPeriodic.

   362      * @see CFlexTimer

   363      */

   364     void After( TTimeIntervalMicroSeconds aInterval );

   365 

   366     /**

   367      * No definition. This function is not to be used through CFlexPeriodic.

   368      * @see CFlexTimer

   369      */

   370     void At( const TTime& aTime );

   371 

   372     /**

   373      * No definition. This function is not to be used through CFlexPeriodic.

   374      * @see CFlexTimer

   375      */

   376     void AtUTC( const TTime& aTime );

   377     

   378     /**

   379      * No definition. This function is not to be used through CFlexPeriodic.

   380      * @see CFlexTimer

   381      */

   382     TInt Configure( TTimeIntervalMicroSeconds32 aWindowSize );

   383 

   384     /**

   385      * Interval value that is used after the initial delay.

   386      */

   387     TTimeIntervalMicroSeconds iInterval;

   388 

   389     /**

   390      * Flex window size that is used after the initial delay.

   391      */

   392     TTimeIntervalMicroSeconds iIntervalWindow;

   393 

   394     /**

   395      * The callback function which is called at the completion of

   396      * flextimer server requests.

   397      */

   398     TCallBack iCallBack;

   399     

   400     /**

   401      * The callback function which is called if error accurs

   402      * somewhere in FlexTimerSystem. i.e. Error code is returned

   403      * to RunL.

   404      */

   405     TCallBack iCallBackError;

   406     

   407     /**

   408      * This member stores information, whether the interval configuration

   409      * should be sent to the server or not.

   410      */

   411     TBool   iSendConfigure;

   412 

   413     };

   414 

   415 #endif /* CFLEXPERIODIC_H */