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:  RFlexTimer class for Flexible Timer server access.

    15  *

    16  */

    17 

    18 /*

    19  * %version: 1 %

    20  */

    21 

    22 #ifndef RFLEXTIMER_H

    23 #define RFLEXTIMER_H

    24 

    25 // INCLUDE FILES

    26 #include <e32std.h> 

    27 

    28 // CLASS DECLARATION

    29 /**

    30  *  Resource class providing access to flexible timer server.

    31  *  

    32  *  This timer class is in many ways similar to RTimer in its use. The

    33  *  main difference is the option to set a timer expiry window. When the timer

    34  *  expiry window has been set to a value greater than zero, requested

    35  *  timeouts may expire at any point of time inside this window. This timer

    36  *  should be used for timed air-interface operations, such as keep-alive

    37  *  messages. The use of normal timers is recommended if the timeouts are not

    38  *  related to data transmission or reception activity in the device.

    39  *  

    40  *  The purpose for a flexible timer is to allow the system the opportunity to

    41  *  align timed behaviour that uses radio resources. For example, when a

    42  *  radio device is otherwise in an idle state, simple keep-alive messaging

    43  *  can be grouped together so that all traffic happens in single bursts

    44  *  instead of being distributed evenly along time timeline. This maximises

    45  *  radio idle time and therefore also battery lifetime.

    46  *  

    47  *  This class defines a client interface for flexible timer server

    48  *  (CFlexTimerServer). When a user requests timeout with RFlexTimer, the

    49  *  server will expire the request non-deterministically within an time window

    50  *  configured by the user. Timer resolution is one second.

    51  *  

    52  *  The timer returns one of the following values for TRequestStatus or any

    53  *  other system-wide error codes:

    54  *  

    55  *  <table border=1 bordercolor="#84B0C7" cellspacing="0" align="center">

    56  *  <tr>

    57  *      <th>Return value</th>

    58  *      <th>Description</th>

    59  *      <th>@c At()</th>

    60  *      <th>@c AtUTC()</th>

    61  *      <th>@c After()</th>

    62  *      <th>@c AfterTicks()</th>

    63  *  </tr>

    64  *  <tr>

    65  *      <td>@c KErrNone</td>

    66  *      <td>Timer has expired normally</td>

    67  *      <td align="center">X</td>

    68  *      <td align="center">X</td>  

    69  *      <td align="center">X</td>

    70  *      <td align="center">X</td>

    71  *  </tr>

    72  *  <tr>

    73  *      <td>@c KErrCancel</td>

    74  *      <td>Timer has been cancelled by @c Cancel()</td>

    75  *      <td align="center">X</td>

    76  *      <td align="center">X</td>

    77  *      <td align="center">X</td>

    78  *      <td align="center">X</td>

    79  *  </tr>

    80  *  <tr>

    81  *      <td>@c KErrAbort</td>

    82  *      <td>Timer has been aborted due time change</td>

    83  *      <td align="center">X</td>

    84  *      <td align="center">X</td>

    85  *      <td align="center">&nbsp;</td>

    86  *      <td align="center">&nbsp;</td>

    87  *  </tr>

    88  *  </table>

    89  *  

    90  *  Example: A user uses Configure-function to set the timer window to

    91  *  2,000,000 microseconds. Next the user requests a timeout with an interval

    92  *  value of 3,000,000 microseconds. Now the timer may expire at any moment

    93  *  after 1,000,000 microseconds and at latest after 3,000,000 microseconds

    94  *  (+ possible timer inaccuracy (timer resolution) ) has passed from the 

    95  *  timeout request. 

    96  *

    97  *  Passing a negative timer interval value or a past time instant 

    98  *  to timer functions will cause a panic . Restarting a timer that is already

    99  *  running will cause panic. Cancel must be used before starting timer again.

   100  *

   101  *  @see CFlexTimer

   102  *  @see CFlexPeriodic

   103  *  @see RTimer

   104  *

   105  *  Examples:

   106  *

   107  *  Synchronous usage of RFlexTimer:

   108  *  @code

   109  *      const TTimeIntervalMicroSeconds KInterval( 900000000 ); // 15 mins

   110  *      const TTimeIntervalMicroSeconds KWindow( 300000000 ); // 5 mins

   111  *

   112  *      TRequestStatus status;

   113  *

   114  *      RFlexTimer timer;

   115  *      User::LeaveIfError( timer.Connect() );

   116  *

   117  *      timer.Configure( KWindow );

   118  *      timer.After( status, KInterval );

   119  *

   120  *      User::WaitForRequest( status );     // Wait till the timer expires

   121  *

   122  *      // Check the request's status

   123  *      if ( status == KErrNone )

   124  *          {

   125  *          // Timer was expired ok

   126  *          }

   127  *      else if ( status == KErrAborted )

   128  *          {

   129  *          // Only for At() and AtUTC()

   130  *          // Timer was aborted by time change

   131  *          }

   132  *      else if ( status == KErrCancel )

   133  *          {

   134  *          // timer.Cancel() was called while the timer was active

   135  *          }

   136  *      else

   137  *          {

   138  *          // Some other error has happened

   139  *          }

   140  *          .

   141  *          .

   142  *          .

   143  *      timer.Close();

   144  *  @endcode

   145  *

   146  *  Asynchronous usage of RFlexTimer (consider using CFlexTimer or 

   147  *  CFlexPeriodic instead of own implementation):

   148  *  

   149  *  Class definition

   150  *  @code

   151  *      class CMyNetworkServiceMonitor : public CActive

   152  *      {

   153  *      public: // Members

   154  *

   155  *          // Public two-phased constructor

   156  *          static CMyNetworkServiceMonitor* NewL(

   157  *              TTimeIntervalMicroSeconds aWindow,

   158  *              TTimeIntervalMicroSeconds aInterval );

   159  *

   160  *          // Destructor

   161  *          virtual ~CMyNetworkServiceMonitor();

   162  *

   163  *      protected: // From CActive

   164  *

   165  *          // Cancel outstanding request. Called by CActive::Cancel().

   166  *          virtual void DoCancel();

   167  *

   168  *          // Handle request completion event  

   169  *          virtual void RunL();

   170  *      

   171  *      private: // Members

   172  *

   173  *          // Constructor

   174  *          CMyNetworkServiceMonitor( TTimeIntervalMicroSeconds aInterval );

   175  *

   176  *          // Second phase constructor

   177  *          void ConstructL( TTimeIntervalMicroSeconds aWindow );

   178  *

   179  *          // Does the network server monitoring.

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

   181  *          void DoNetworkServiceMonitoring();

   182  *      

   183  *      private: // Data

   184  *          RFlexTimer iTimer;

   185  *          TTimeIntervalMicroSeconds iInterval;

   186  *      };

   187  *  @endcode

   188  *

   189  *  @code

   190  *  CMyNetworkServiceMonitor::CMyNetworkServiceMonitor( 

   191  *      TTimeIntervalMicroSeconds aInterval ):

   192  *      CActive( CActive::EPriorityStandard ),

   193  *      iInterval( aInterval )

   194  *      {

   195  *      // Nothing to do

   196  *      } 

   197  *

   198  *  // -----------------------------------------------------------------------------

   199  *  //

   200  *  void CMyNetworkServiceMonitor::ConstructL( 

   201  *      TTimeIntervalMicroSeconds aWindow )

   202  *      {

   203  *      User::LeaveIfError( iTimer.Connect() );

   204  *      iTimer.Configure( aWindow );

   205  *      }

   206  *

   207  *  // -----------------------------------------------------------------------------

   208  *  //

   209  *  CMyNetworkServiceMonitor* CMyNetworkServiceMonitor::NewL( 

   210  *      TTimeIntervalMicroSeconds aWindow,

   211  *      TTimeIntervalMicroSeconds aInterval )

   212  *      {

   213  *      CMyNetworkServerMonitor* self =

   214  *          new (ELeave) CMyNetworkServerMonitor( aInterval );

   215  *      CleanupStack::PushL( self );

   216  *      self->ConstructL( aWindow );

   217  *      CleanupStack::Pop( self );

   218  *

   219  *      iTimer.After( TTimeIntervalMicroSeconds( 0 ) );

   220  *      SetActive();

   221  *

   222  *      return self;

   223  *      }

   224  *

   225  *  // -----------------------------------------------------------------------------

   226  *  //

   227  *  CMyNetworkServiceMonitor::~CMyNetworkServiceMonitor()

   228  *      {

   229  *      Cancel();       // Calls CActive::Cancel()

   230  *      iTimer.Close(); // Close the timer handle

   231  *      }

   232  *      

   233  *  // -----------------------------------------------------------------------------

   234  *  //

   235  *  void CMyNetworkServiceMonitor::DoCancel()

   236  *      {

   237  *      iTimer.Cancel();

   238  *      }

   239  *

   240  *  // -----------------------------------------------------------------------------

   241  *  //

   242  *  void CMyNetworkServiceMonitor::RunL()

   243  *      {

   244  *      // Note! If used RFlexTimer::At() or RFlexTimer::AtUTC()

   245  *      // iStatus == KErrAbort should also be handled.

   246  *      

   247  *      if ( iStatus == KErrNone )

   248  *          {

   249  *          // Do the network server monitor actions

   250  *          DoNetworkServiceMonitoring();

   251  *

   252  *           // Refresh the timer

   253  *          iTimer.After( iInterval );

   254  *          SetActive();

   255  *          }

   256  *      else if ( iStatus == KErrCancel )

   257  *          {

   258  *          // Timer was cancelled. Do not activate it again... 

   259  *          }

   260  *      else

   261  *          {

   262  *          // Handle the error by implementing RunError()

   263  *          // See also: CActive::RunError()

   264  *          User::Leave( iStatus );

   265  *          }

   266  *      }

   267  *  @endcode

   268  */

   269 class RFlexTimer : public RSessionBase

   270     {

   271 public:

   272     // Constructors and destructors

   273 

   274     /**

   275      * Constructs the object.

   276      */

   277     IMPORT_C RFlexTimer();

   278 

   279     /**

   280      * Destructs the object.

   281      */

   282     IMPORT_C ~RFlexTimer();

   283 

   284     /**

   285      * Connects to the timer server. This function needs to be called before

   286      * any timeouts can be requested.

   287      * 

   288      * @return KErrNone on success. KErrNotSupported if client's and server's

   289      * versions don't match. Otherwise returns one of the system-wide error

   290      * codes.

   291      * @panic RFlexTimer 33 Connected is called twice without closing the

   292      * handle first

   293      * 

   294      * Example:

   295      * @code

   296      *      RFlexTimer timer;

   297      *      User::LeaveIfError( timer.Connect() );

   298      *          .

   299      *          . // Set timer/wait for expiration.

   300      *          .

   301      *      timer.Close();  // Close the handle

   302      * @endcode

   303      */

   304     IMPORT_C TInt Connect();

   305 

   306     /**

   307      * Cancels the timer. Active timer will be completed with status 

   308      * KErrCancel. If there are no active timer, Cancel() does nothing.

   309      * 

   310      * @panic KERN-EXEC 0 Cancel() was called before Connect()

   311      * 

   312      * Example:

   313      * @code

   314      *      RFlexTimer timer;

   315      *      User::LeaveIfError( timer.Connect() );

   316      *          .

   317      *          .

   318      *          .

   319      *      // Oops, no need to wait the timer expiration

   320      *      timer.Cancel(); // Cancel the pending timer    

   321      *          .

   322      *          .

   323      *          .  

   324      *      timer.Close();  // Close the handle

   325      * @endcode

   326      */

   327     IMPORT_C void Cancel();

   328 

   329     /**

   330      * An asynchronous timeout request to the flexible timer server.

   331      * Fire timer at latest on the given 32-bit interval.

   332      * 

   333      * @param aStatus active object to be used for getting responses.	

   334      * @param aInterval the interval value until which the timer must expire.

   335      * 

   336      * @panic RFlexTimer 1  aInterval is negative

   337      * @panic RFlexTimer 15 Timer is already active. Wait it to expire or

   338      * cancel it first.

   339      *

   340      * Example:

   341      * @code

   342      *      const TTimeIntervalMicroSeconds32 KInterval32( 300000000 ); // 5 mins  

   343      *      const TTimeIntervalMicroSeconds32 KWindow32( 120000000 ); // 2 mins  

   344      *      

   345      *      TRequestStatus status;

   346      *      RFlexTimer timer;

   347      *      

   348      *      User:LeaveIfError( timer.Connect() );

   349      *      timer.Configure( KWindow32 );

   350      *      timer.After( status, KInterval32 );

   351      *      

   352      *      User::WaitForRequest( status ); // Wait timer to expire, synchronous

   353      *          .

   354      *          .

   355      *          .

   356      *      timer.Close();  // Close the handle

   357      * @endcode 

   358      */

   359     IMPORT_C void After( TRequestStatus& aStatus,

   360                          TTimeIntervalMicroSeconds32 aInterval );

   361     

   362     /**

   363      * An asynchronous timeout request to the flexible timer server.

   364      * Fire timer at latest on the given 64-bit interval.

   365      * @param aStatus active object to be used for getting responses.   

   366      * @param aInterval the interval value until which the timer must expire.   

   367      * @panic RFlexTimer 1  aInterval is negative

   368      * @panic RFlexTimer 15 Timer is already active. Wait it to expire or

   369      * cancel it first.

   370      * @panic RFlexTimer 24 aInterval is too big (max 730 days)

   371      * 

   372      * Example:

   373      * @code

   374      *      const TTimeIntervalMicroSeconds KInterval64( 300000000 ); // 5 mins

   375      *

   376      *      TRequestStatus status;

   377      *      RFlexTimer timer;

   378      *      

   379      *      User::LeaveIfError( timer.Connect() );

   380      *      timer.After( status, KInterval64 );

   381      *      

   382      *      User::WaitForRequest( status ); // Wait timer to expire, synchronous

   383      *          .

   384      *          .

   385      *          .

   386      *      timer.Close();  // Close the handle

   387      * @endcode

   388      */

   389     IMPORT_C void After( TRequestStatus& aStatus,

   390                          TTimeIntervalMicroSeconds aInterval );

   391 

   392     /**

   393      * An asynchronous timeout request to the flexible timer server.

   394      * Fire timer at latest after the given number of system ticks.

   395      * 

   396      * By default the system tick is 1/64 second. The exact value for one

   397      * system tick can be retrieve via Symbian OS HAL API:

   398      * 

   399      * @code

   400      *      TInt tickInMicroSeconds;

   401      *      HAL::Get( HAL::ESystemTickPeriod, tickInMicroSeconds );

   402      * @endcode

   403      * 

   404      * @param aStatus active object to be used for getting responses.

   405      * @param aTicks the interval value until which the timer must expire. 	

   406      * @panic RFlexTimer 2  aTicks is negative

   407      * @panic RFlexTimer 15 Timer is already active. Wait it to expire or

   408      * cancel it first.

   409      * 

   410      * Example:

   411      * @code

   412      *      const TInt KIntervalInTicks( 57600 ); // 15 mins (1 tick = 15625 microseconds)

   413      *

   414      *      TRequestStatus status;

   415      *      RFlexTimer timer;

   416      *      

   417      *      User::LeaveIfError( timer.Connect() );

   418      *      timer.AfterTicks( status, KIntervalInTicks );

   419      *      

   420      *      User::WaitForRequest( status ); // Wait timer to expire, synchronous

   421      *          .

   422      *          .

   423      *          .

   424      *      timer.Close();  // Close the handle

   425      * @endcode

   426      */

   427     IMPORT_C void AfterTicks( TRequestStatus& aStatus, TInt aTicks );

   428 

   429     /**

   430      * An asynchronous timeout request to the flexible timer server.

   431      * Fire timer between at latest by the given time value. If the system

   432      * time changes before the timer requested with At-function expires, it

   433      * will cancel itself. This will result in the aStatus argument to have

   434      * KErrAbort-value.

   435      * @param aStatus active object to be used for getting responses.

   436      * @param aTime indicates the latest system-time when this timer should

   437      * be fired.

   438      * @panic RFlexTimer 3  aTime is in the past

   439      * @panic RFlexTimer 15 Timer is already active. Wait it to expire or

   440      * cancel it first.

   441      * @panic RFlexTimer 24 aTime is too far in the future (max 730 days)

   442      * 

   443      * Example:

   444      * @code

   445      *      const TTimeIntervalMinutes KWaitTime( 5 );

   446      *      

   447      *      TRequestStatus status;

   448      *      RFlexTimer timer;

   449      *      User::LeaveIfError( timer.Connect() );

   450      *      

   451      *      TTime now;

   452      *      now.HomeTime();

   453      *

   454      *      timer.At( status, now + KWaitTime );

   455      *      

   456      *      User::WaitForRequest( status ); // Wait timer to expire, synchronous

   457      *          .

   458      *          .

   459      *          .

   460      *      timer.Close();  // Close the handle

   461      * @endcode

   462      */

   463     IMPORT_C void At( TRequestStatus& aStatus, const TTime& aTime );

   464 

   465     /**

   466      * An asynchronous timeout request to the flexible timer server.

   467      * Fire timer between at latest by the given UTC (Coordinated Universal

   468      * Time) time value. If the system time changes before the timer requested

   469      * with AtUTC-function expires, it will cancel itself. This will result in

   470      * the aStatus argument to have KErrAbort-value.

   471      * @param aStatus active object to be used for getting responses.

   472      * @param aTime indicates the latest UTC time when this timer should be

   473      * fired. 

   474      * @panic RFlexTimer 4  aTime is in the past

   475      * @panic RFlexTimer 15 Timer is already active. Wait it to expire or

   476      * cancel it first.

   477      * @panic RFlexTimer 24 aTime is too far in the future (max 730 days)

   478      * 

   479      * Example:

   480      * @code

   481      *      const TTimeIntervalMinutes KWaitTime( 5 );

   482      *

   483      *      TRequestStatus status;

   484      *      RFlexTimer timer;

   485      *      User::LeaveIfError( timer.Connect() );

   486      *

   487      *      TTime nowUtc;

   488      *      nowUtc.UniversalTime();

   489      *

   490      *      timer.At( status, nowUtc + KWaitTime );

   491      *

   492      *      User::WaitForRequest( status ); // Wait timer to expire, synchronous

   493      *          .

   494      *          .

   495      *          .

   496      *      timer.Close();  // Close the handle

   497      * @endcode

   498      */

   499     IMPORT_C void AtUTC( TRequestStatus& aStatus, const TTime& aTime );

   500 

   501     /**

   502      * Sets the window size in which alignment is possible for the timer.

   503      * This is a synchronous command - it will return only after the server

   504      * has completed the configuration message. If the timer is already

   505      * running, it will return KErrInUse.

   506      * 

   507      * If user is not calling this function in prior to start timer, default

   508      * value will be used as time window. Default value is currently 20%

   509      * of total timer running time 

   510      * (0.2 * (requested_expiry_time - current_time)) and this value is in 

   511      * subject to change.

   512      * 

   513 	 * If the user wishes to restore the default window size behaviour,

   514      * a new timer is needed. 

   515 	 *

   516      * Giving zero value as aWindowSize parameter, means that timer is fired

   517      * precisely at requested time.

   518 	 *

   519      * @param aWindowSize is the window size in 32-bit microseconds in which

   520      * alignment is possible.

   521      *

   522      * @return KErrNone on success, KErrInUse if timer is set (wait it to be

   523      * expired or cancel it before configuring). Otherwise returns one of the 

   524      * system-wide error codes.

   525      *

   526      * @panic RFlexTimer 5  aWindowSize is negative

   527      * 

   528      * Example:

   529      * @code

   530      *      const TTimeIntervalMicroSeconds32 KWindow32( 120000000 ); // 2 mins

   531      *

   532      *      RFlexTimer timer;

   533      *      User::LeaveIfError( timer.Connect() );

   534      *      

   535      *      timer.Configure( KWindow32 );

   536      *          .

   537      *          .

   538      *          .

   539      *      timer.Close();  // Close the handle

   540      * @endcode

   541      */

   542     IMPORT_C TInt Configure( TTimeIntervalMicroSeconds32 aWindowSize );

   543     

   544     /**

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

   546      * 

   547      * @param aWindowSize is the window size in 64-bit microseconds in which

   548      * alignment is possible.

   549      * 

   550      * @return KErrNone on success, KErrInUse if timer is set, wait it to 

   551      * expire or cancel it before configuring. Otherwise returns one of the 

   552      * system-wide error codes.

   553      * 

   554      * @panic RFlexTimer 5  aWindowSize is negative

   555      * @panic RFlexTimer 24 aWindowSize is too big (max 730 days)

   556      * 

   557      * @see TInt Configure( TTimeIntervalMicroSeconds32 )

   558      * 

   559      * Example:

   560      * @code

   561      *      const TTimeIntervalMicroSeconds KWindow64( 120000000 ); // 2 mins

   562      *

   563      *      RFlexTimer timer;

   564      *      User::LeaveIfError( timer.Connect() );

   565      *      

   566      *      timer.Configure( KWindow64 );

   567      *          .

   568      *          .

   569      *          .

   570      *      timer.Close();  // Close the handle

   571      * @endcode

   572      */

   573     IMPORT_C TInt Configure( TTimeIntervalMicroSeconds aWindowSize );

   574 

   575 private:

   576     

   577     /**

   578      * Gets the version number.

   579      * @return The version.

   580      */

   581     TVersion Version() const;

   582 

   583     /**

   584      * Connects to the server. If server does not exist, it is created.

   585      * @return KErrNone on success. Otherwise returns one of the system-wide

   586      * error codes.

   587      */

   588     TInt StartServer();

   589 

   590     };

   591 

   592 #endif // RFLEXTIMER_H

   593 

   594 // End of File