diff -r c16e04725da3 -r 5c4486441ae6 ipcm_plat/flextimer_api/inc/flextimer.h --- /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 +#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: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Return valueDescription@c At()@c AtUTC()@c After()
@c KErrNoneTimer has expired normallyXXX
@c KErrCancelTimer has been cancelledXXX
@c KErrAbortTimer has been aborted due time changeXX 
+ * + * 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 + +