/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

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

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  CFlexPeriodic class for Flexible Timer server access.

 *

 */

/*

 * %version: 1 %

 */

#ifndef CFLEXPERIODIC_H

#define CFLEXPERIODIC_H

// INCLUDE FILES

#include "flextimer.h"

// CLASS DECLARATION

/**

 *  Class providing access to flexible periodic timer service.

 *  This class inherits CFlexTimer and provides user with a periodic

 *  timer very similar to CPeriodic with the exception that both

 *  the initial delay and the consequent intervals have flexible

 *  windows of opportunity during which they may expire.

 *  

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

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

 *  See RFlexTimer for details about default window. 

 *  

 *  Note that when CFlexPeriodic expires next expiry interval always starts 

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

 *  "slide" when comparing to CPeriodic. 

 *  

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

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

 *  

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

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

 *

 *  @see CFlexTimer

 *  @see RFlexTimer

 *  @see CPeriodic

 *

 *  Example:

 *  

 *  Class definition:

 *  @code

 *  // Forward declaration

 *  class CFlexPeriodic;

 *

 *  // Class definition

 *  class CMyNetworkServiceMonitor : public CBase

 *      {

 *      public: // Members

 *

 *          // Destructor

 *          virtual ~CMyNetworkServiceMonitor();

 *

 *          // Two-phased constructor

 *          static CMyNetworkServiceMonitor* NewL(

 *              TTimeIntervalMicroSeconds aWindow,

 *              TTimeIntervalMicroSeconds aInterval );

 *

 *      private: // Members

 *

 *          // Constructor

 *          CMyNetworkServiceMonitor();

 *

 *          // 2nd phase constuctor

 *          void ConstructL(

 *              TTimeIntervalMicroSeconds aWindow,

 *              TTimeIntervalMicroSeconds aInterval );

 *

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

 *          static TInt DoMonitoring( TAny* aArgument );

 *

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

 *          // TCallBack.

 *          static TInt HandleError( TAny* aArgument );

 *

 *          // Does the network server monitoring.

 *          // Implementation is not provided by this example.

 *          DoNetworkServiceMonitoring();

 *

 *      private: // Data

 *

 *          // Owns. Flexible periodic timer.

 *          CFlexPeriodic* iTimer;

 *      };

 *  @endcode

 *

 *  Class implementation:

 *  @code

 *  // ---------------------------------------------------------------------------

 *  //

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

 *      {

 *      // Nothing to do

 *      }

 *

 *  // ---------------------------------------------------------------------------

 *  //

 *  CMyNetworkServiceMonitor::~CMyNetworkServiceMonitor()

 *      {

 *      if ( iTimer != NULL )

 *          {

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

 *          delete iTimer;

 *          }

 *      }

 *

 *  // ---------------------------------------------------------------------------

 *  //

 *  CMyNetworkServiceMonitor* CMyNetworkServiceMonitor::NewL(

 *      TTimeIntervalMicroSeconds aWindow,

 *      TTimeIntervalMicroSeconds aInterval )

 *      {

 *      CMyNetworkServiceMonitor* self =

 *          new (ELeave) CMyNetworkServiceMonitor;

 *      CleanupStack::PushL( self );

 *      self->ConstructL( aWindow, aInterval );

 *      CleanupStack::Pop( self );

 *      return self;

 *      }

 *

 *  // ---------------------------------------------------------------------------

 *  //

 *  void CMyNetworkServiceMonitor::ConstructL(

 *      TTimeIntervalMicroSeconds aWindow,

 *      TTimeIntervalMicroSeconds aInterval )

 *      {

 *      // Constants

 *      const TTimeIntervalMicroSeconds KNoWindow( 0 );

 *      const TTimeIntervalMicroSeconds KImmediately( 0 );

 *

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

 *

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

 *      CleanupStack::PushL( iTimer );

 *

 *      // Set delay window 0 minute

 *      User::LeaveIfError( 

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

 *

 *      // Start the timer, 1st call immediately

 *      iTimer->Start(

 *          KImmediately,

 *          aInterval,

 *          TCallBack( DoMonitoring, this ),

 *          TCallBack( HandleError, this ) );

 *

 *      CleanupStack::Pop( iTimer );

 *      }

 *

 *  // ---------------------------------------------------------------------------

 *  //

 *  TInt CMyNetworkServiceMonitor::DoMonitoring( TAny* aArgument )

 *      {

 *      CMyNetworkServiceMonitor* monitor =

 *          static_cast<CMyNetworkServiceMonitor*>( aArgument );

 *

 *      monitor->DoNetworkServerMonitoring();

 *      return KErrNone;

 *      }

 *     

 *  // ---------------------------------------------------------------------------

 *  //

 *  TInt CMyNetworkServiceMonitor::HandleError( TAny* aArgument )

 *      {

 *      CMyNetworkServiceMonitor* monitor =

 *          static_cast<CMyNetworkServiceMonitor*>( aArgument );

 *

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

 *      // here.

 *          .

 *          .

 *          .

 *      return KErrNone;

 *      }     

 *  @endcode

 */

class CFlexPeriodic : public CFlexTimer

    {

public:

    /**

     * A leaving constructor for the object.

     * 

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

     * 

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

     * 

     * @leave KErrMemory Not enough memory

     */

    static IMPORT_C CFlexPeriodic* NewL( TInt aPriority );

    /**

     * Destructor for the object.

     */

    virtual IMPORT_C ~CFlexPeriodic();

    /**

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

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

     * the aCallBack function is called periodically after anInterval from the

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

     * tolerancies indicated by the flexibility windows. The flexibility

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

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

     * values.

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

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

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

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

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

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

     * microsecond.

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

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

     * @param aCallBackError optional, but recommended parameter is a 

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

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

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

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

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

     * resources.

     *

     * @panic CFlexPeriodic  6 aDelay is negative

     * @panic CFlexPeriodic  7 aInterval is zero or negative

     * @panic CFlexPeriodic 31 aCallBack.iFunction is NULL

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

     * cancelling the timer first

     *

     * @see Configure

     */

    IMPORT_C void Start( TTimeIntervalMicroSeconds32 aDelay,

                         TTimeIntervalMicroSeconds32 anInterval,

                         TCallBack aCallBack,

                         TCallBack aCallBackError = TCallBack() );

    /**

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

     * interval values.

     *

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

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

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

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

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

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

     * microsecond.

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

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

     * @param aCallBackError optional, but recommended parameter is a 

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

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

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

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

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

     * resources.

     *

     * @panic CFlexPeriodic  6 aDelay is negative

     * @panic CFlexPeriodic  7 aInterval is zero or negative

     * @panic CFlexPeriodic 31 aCallBack.iFunction is NULL

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

     * cancelling the timer first

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

     *

     * @see Configure

     */

    IMPORT_C void Start( TTimeIntervalMicroSeconds aDelay,

                         TTimeIntervalMicroSeconds anInterval,

                         TCallBack aCallBack,

                         TCallBack aCallBackError = TCallBack() );

    /**

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

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

     * been Started, this function returns an error code.

     * 

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

     * sizes. @see RFlexTimer::Configure

     *

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

     * microseconds for the initial delay.

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

     * microseconds for the intervals after the initial delay.

     *

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

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

     * into the timer and need to be configured again.

     *

     * @panic CFlexPeriodic  8 aDelayWindow is negative

     * @panic CFlexPeriodic  9 aIntervalWindow is negative

     */

    IMPORT_C TInt Configure( TTimeIntervalMicroSeconds32 aDelayWindow,

                             TTimeIntervalMicroSeconds32 aIntervalWindow );

    /**

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

     *

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

     * microseconds for the initial delay.

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

     * microseconds for the intervals after the initial delay.

     *

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

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

     * into the timer and need to be configured again.

     *

     * @panic CFlexPeriodic  8 aDelayWindow is negative

     * @panic CFlexPeriodic  9 aIntervalWindow is negative

     * @panic RFlexTimer    24 aDelayWindow or aIntervalWindow is too long 

     * (over 730 days)

     */

    IMPORT_C TInt Configure( TTimeIntervalMicroSeconds aDelayWindow,

                             TTimeIntervalMicroSeconds aIntervalWindow );

protected:

    /**

     * Inherited from CActive.

     */

    virtual void RunL();

private:

    /**

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

     */

    void ConstructL();

    /**

     * Private constructor for the object.

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

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

     * owned by the scheduler.

     */

    CFlexPeriodic( TInt aPriority );

private:

    /**

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

     * @see CFlexTimer

     */

    void After( TTimeIntervalMicroSeconds32 aInterval );

    /**

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

     * @see CFlexTimer

     */

    void After( TTimeIntervalMicroSeconds aInterval );

    /**

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

     * @see CFlexTimer

     */

    void At( const TTime& aTime );

    /**

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

     * @see CFlexTimer

     */

    void AtUTC( const TTime& aTime );

    /**

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

     * @see CFlexTimer

     */

    TInt Configure( TTimeIntervalMicroSeconds32 aWindowSize );

    /**

     * Interval value that is used after the initial delay.

     */

    TTimeIntervalMicroSeconds iInterval;

    /**

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

     */

    TTimeIntervalMicroSeconds iIntervalWindow;

    /**

     * The callback function which is called at the completion of

     * flextimer server requests.

     */

    TCallBack iCallBack;

    /**

     * The callback function which is called if error accurs

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

     * to RunL.

     */

    TCallBack iCallBackError;

    /**

     * This member stores information, whether the interval configuration

     * should be sent to the server or not.

     */

    TBool   iSendConfigure;

    };

#endif /* CFLEXPERIODIC_H */