--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ipcm_plat/flextimer_api/inc/flextimer.h Mon May 24 20:51:35 2010 +0300
@@ -0,0 +1,363 @@
+/*
+ * 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: CFlexTimer class for Flexible Timer server access.
+ *
+ */
+
+/*
+ * %version: 1 %
+ */
+
+#ifndef CFLEXTIMER_H
+#define CFLEXTIMER_H
+
+// INCLUDE FILES
+#include <e32base.h>
+#include "rflextimer.h"
+
+// CLASS DECLARATION
+/**
+ * Class providing access to flexible timer service.
+ * This class uses RFlexTimer to provide user with timeout services. Each
+ * timeout that is requested with this class has a time window during which
+ * it may expire. The size of this window needs to be configured by the user.
+ * If not configured, a default window size is used. See RFlexTimer for
+ * details about default window.
+ *
+ * This class can not be instantiated; it needs to be inherited by a
+ * user's derived class. The user also needs to implement the RunL
+ * function.
+ *
+ * The timer returns one of the following values for TRequestStatus or any
+ * other system-wide error codes:
+ *
+ * <table border=1 bordercolor="#84B0C7" cellspacing="0" align="center">
+ * <tr>
+ * <th>Return value</th>
+ * <th>Description</th>
+ * <th>@c At()</th>
+ * <th>@c AtUTC()</th>
+ * <th>@c After()</th>
+ * </tr>
+ * <tr>
+ * <td>@c KErrNone</td>
+ * <td>Timer has expired normally</td>
+ * <td align="center">X</td>
+ * <td align="center">X</td>
+ * <td align="center">X</td>
+ * </tr>
+ * <tr>
+ * <td>@c KErrCancel</td>
+ * <td>Timer has been cancelled</td>
+ * <td align="center">X</td>
+ * <td align="center">X</td>
+ * <td align="center">X</td>
+ * </tr>
+ * <tr>
+ * <td>@c KErrAbort</td>
+ * <td>Timer has been aborted due time change</td>
+ * <td align="center">X</td>
+ * <td align="center">X</td>
+ * <td align="center"> </td>
+ * </tr>
+ * </table>
+ *
+ * Any object derived from this class needs to connect to the flextimer
+ * server by calling CFlexTimer::ConstructL() function before calling
+ * configuration or timeout functions. Otherwise any timeout function will
+ * result in panic.
+ *
+ * @see RFlexTimer
+ * @see CTimer
+ *
+ * Example:
+ *
+ * Class definition:
+ * @code
+ * class CMyNetworkServiceMonitor : public CFlexTimer
+ * {
+ * public: // Members
+ *
+ * // Public two-phased constructor
+ * static CMyNetworkServiceMonitor* NewL(
+ * TTimeIntervalMicroSeconds aWindow,
+ * TTimeIntervalMicroSeconds aInterval );
+ *
+ * // Destructor
+ * virtual ~CMyNetworkServiceMonitor();
+ *
+ * protected: // From CActive
+ *
+ * // Handles an active object's request completion event
+ * virtual void RunL();
+ *
+ * private: // Members
+ *
+ * // Private constructor
+ * CMyNetworkServiceMonitor( TTimeIntervalMicroSeconds aInterval );
+ *
+ * // Second phase constructor
+ * void ConstructL( TTimeIntervalMicroSeconds aWindow );
+ *
+ * // Does the network server monitoring.
+ * // Implementation is not provided by this example.
+ * DoNetworkServiceMonitoring();
+ *
+ * private: // Data
+ *
+ * TTimeIntervalMicroSeconds iInterval;
+ * };
+ * @endcode
+ *
+ * Class implementation:
+ * @code
+ * CMyNetworkServiceMonitor::CMyNetworkServiceMonitor( TTimeIntervalMicroSeconds aInterval ) :
+ * CFlexTimer( CActive::EPriorityStandard ),
+ * iInterval( aInterval )
+ * {
+ * // Nothing to do
+ * }
+ *
+ * // ---------------------------------------------------------------------------
+ * //
+ * CMyNetworkServiceMonitor::~CMyNetworkServiceMonitor()
+ * {
+ * Cancel(); // DoCancel() is implemented by CFlexTimer
+ * }
+ *
+ * // ---------------------------------------------------------------------------
+ * //
+ * void CMyNetworkServiceMonitor::ConstructL( TTimeIntervalMicroSeconds aWindow )
+ * {
+ * const TTimeIntervalMicroSeconds KImmediately( 0 );
+ *
+ * CFlexTimer::ConstructL();
+ * CActiveScheduler::Add( this );
+ *
+ * Configure( aWindow );
+ *
+ * After( KImmediately ); // Kick-off the timer
+ * }
+ *
+ * // ---------------------------------------------------------------------------
+ * //
+ * CMyNetworkServiceMonitor* CMyNetworkServiceMonitor::NewL(
+ * TTimeIntervalMicroSeconds aWindow,
+ * TTimeIntervalMicroSeconds aInterval )
+ * {
+ * CMyNetworkServiceMonitor* self =
+ * new (ELeave) CMyNetworkServiceMonitor( aInterval );
+ * CleanupStack::PushL( self );
+ * self->ConstructL( aWindow );
+ * CleanupStack::Pop( self );
+ * return self;
+ * }
+ *
+ * // ---------------------------------------------------------------------------
+ * //
+ * void CMyNetworkServiceMonitor::RunL()
+ * {
+ * // Note! If used RFlexTimer::At() or RFlexTimer::AtUTC()
+ * // iStatus == KErrAbort should also be handled.
+ *
+ * if ( iStatus == KErrNone )
+ * {
+ * // Do the network server monitor actions
+ * DoNetworkServiceMonitoring();
+ *
+ * // Refresh the timer
+ * After( iInterval );
+ * }
+ * else if ( iStatus == KErrCancel )
+ * {
+ * // Timer was cancelled. Do not activate it again...
+ * }
+ * else
+ * {
+ * // Handle the error by implementing RunError()
+ * // See also: CActive::RunError()
+ * User::Leave( iStatus );
+ * }
+ * }
+ * @endcode
+ */
+class CFlexTimer : public CActive
+ {
+public:
+
+ /**
+ * Destructs the object.
+ */
+ IMPORT_C virtual ~CFlexTimer();
+
+ /**
+ * Fire timer at latest on the given interval. 32-bit interval value.
+ * @param aInterval the interval value until which the timer must expire.
+ *
+ * @panic CFlexTimer 10 CFlexTimer::ConstructL() has not been called yet
+ * @panic RFlexTimer 15 Timer is already active. Wait it to expire or
+ * cancel it first.
+ * @panic RFlexTimer 1 aInterval is negative
+ *
+ * Example:
+ * @code
+ * const TTimeIntervalMicroSeconds32 KInterval32( 600000000 ); // 10 min
+ * After( KInterval32 );
+ * @endcode
+ */
+ IMPORT_C void After( TTimeIntervalMicroSeconds32 aInterval );
+
+ /**
+ * Fire timer at latest on the given interval. 64-bit interval value.
+ *
+ * @param aInterval the interval value until which the timer must expire.
+ *
+ * @panic CFlexTimer 10 CFlexTimer::ConstructL() has not been called yet
+ * @panic RFlexTimer 1 aInterval is negative
+ * @panic RFlexTimer 15 Timer is already active. Wait it to expire or
+ * cancel it first.
+ * @panic RFlexTimer 24 aInterval is too big (over 730 days)
+ *
+ * Example:
+ * @code
+ * const TTimeIntervalMicroSeconds KInterval64( 600000000 ); // 10 min
+ * After( KInterval64 );
+ * @endcode
+ */
+ IMPORT_C void After( TTimeIntervalMicroSeconds aInterval );
+
+ /**
+ * Fire timer at latest by the given time value. The time value provided
+ * here is related to HomeTime. @see TTime. If the system
+ * time changes before the timer requested with At-function expires, it
+ * will cancel itself. This will result in the aStatus argument to have
+ * KErrAbort-value.
+ *
+ * @param aTime indicates the latest time when this timer should be fired.
+ *
+ * @panic CFlexTimer 10 CFlexTimer::ConstructL() has not been called yet
+ * @panic RFlexTimer 3 aTime is in the past
+ * @panic RFlexTimer 15 Timer is already active. Wait it to expire or
+ * cancel it first.
+ * @panic RFlexTimer 24 aTime is too far to the future (over 730 days)
+ *
+ * Example:
+ * @code
+ * const TTimeIntervalMinutes KWaitTime( 5 );
+ *
+ * TTime now;
+ * now.HomeTime();
+ *
+ * At( nowUtc + KWaitTime );
+ * @endcode
+ */
+ IMPORT_C void At( const TTime& aTime );
+
+ /**
+ * Fire timer at latest by the given UTC (Coordinated Universal Time)
+ * time value. If the system
+ * time changes before the timer requested with At-function expires, it
+ * will cancel itself. This will result in the aStatus argument to have
+ * KErrAbort-value.
+ * @param aTime indicates the latest UTC time when this timer should be
+ * fired.
+ *
+ * @panic CFlexTimer 10 CFlexTimer::ConstructL() has not been called yet
+ * @panic RFlexTimer 3 aTime is in the past
+ * @panic RFlexTimer 15 Timer is already active. Wait it to expire or
+ * cancel it first.
+ * @panic RFlexTimer 24 aTime is too far to the future (over 730 days)
+ *
+ * Example:
+ * @code
+ * const TTimeIntervalMinutes KWaitTime( 5 );
+ *
+ * TTime nowUtc;
+ * nowUtc.UniversalTime();
+ *
+ * AtUTC( nowUtc + KWaitTime );
+ * @endcode
+ */
+ IMPORT_C void AtUTC( const TTime& aTime );
+
+ /**
+ * Sets the window size in which flexibility is possible for the timer.
+ * @see RFlexTimer::Configure
+ * @param aWindowSize is the window size in 32-bit microseconds in which
+ * timer flexiblity is possible.
+ * @return KErrNone on success. KErrInUse, if timer has been
+ * started already.
+ *
+ * @panic CFlexTimer 10 CFlexTimer::ConstructL() has not been called yet
+ * @panic RFlexTimer 5 aWindowSize is negative
+ *
+ * Example:
+ * @code
+ * const TTimeIntervalMicroSeconds32 KWindow32( 120000000 ); // 2 mins
+ * Configure( KWindow32 );
+ * @endcode
+ */
+ IMPORT_C TInt Configure( TTimeIntervalMicroSeconds32 aWindowSize );
+
+ /**
+ * Sets the window size in which flexibility is possible for the timer.
+ * @see RFlexTimer::Configure
+ * @param aWindowSize is the window size in 64-bit microseconds in which
+ * timer flexiblity is possible.
+ * @return KErrNone on success. KErrInUse, if timer has been
+ * started already.
+ *
+ * @panic CFlexTimer 10 CFlexTimer::ConstructL() has not been called yet
+ * @panic RFlexTimer 5 aWindowSize is negative
+ * @panic RFlexTimer 24 aWindowSize is too big (max 730 days)
+ *
+ * Example:
+ * @code
+ * const TTimeIntervalMicroSeconds KWindow64( 120000000 ); // 2 mins
+ * Configure( KWindow64 );
+ * @endcode
+ */
+ IMPORT_C TInt Configure( TTimeIntervalMicroSeconds aWindowSize );
+
+protected:
+
+ /**
+ * 2nd phase constructor for this the object. Connects to the flextimer
+ * server and creates a session. This function needs to be called by the
+ * object that is derived from this class.
+ */
+ IMPORT_C void ConstructL();
+
+ /**
+ * Constructs the object.
+ */
+ IMPORT_C CFlexTimer( TInt aPriority );
+
+ /**
+ * Inherited from CActive.
+ */
+ IMPORT_C virtual void DoCancel();
+
+private:
+
+ /**
+ * The timer resource used by this object.
+ */
+ RFlexTimer iTimer;
+
+ };
+
+#endif // CFLEXTIMER_H
+
+