RTimer Class Reference

#include <e32std.h>

class RTimer : public RHandleBase

Inherits from

RTimer
- RHandleBase

Public Member Functions
IMPORT_C void	After(TRequestStatus &, TTimeIntervalMicroSeconds32)
IMPORT_C void	AfterTicks(TRequestStatus &, TInt)
IMPORT_C void	AgainHighRes(TRequestStatus &, TTimeIntervalMicroSeconds32)
IMPORT_C void	At(TRequestStatus &, const TTime &)
IMPORT_C void	AtUTC(TRequestStatus &, const TTime &)
IMPORT_C void	Cancel()
IMPORT_C TInt	CreateLocal()
IMPORT_C void	HighRes(TRequestStatus &, TTimeIntervalMicroSeconds32)
IMPORT_C void	Inactivity(TRequestStatus &, TTimeIntervalSeconds)
IMPORT_C void	Lock(TRequestStatus &, TTimerLockSpec)

Inherited Attributes
	RHandleBase::iHandle

Inherited Enumerations
	RHandleBase:TAttributes

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::Close()
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RHandleBase::SetReturnedHandle(TInt)
	RHandleBase::SetReturnedHandle(TInt,RHandleBase &)

Detailed Description

Asynchronous timer services.

Five types of asynchronous request are supported by the class:

1. Requesting an event after a specified interval

2. Requesting an event at a specified system time

3. Requesting a timer event on a specific second fraction

4. Requesting an event if an interval elapses with no user activity.

5. Requesting an event after a specified interval, to a resolution of 1ms.

Each of these requests can be cancelled.

The timer exists from its creation, following a call to RTimer::CreateLocal(), until it is destroyed by a call to the Close() member function of the base class RHandleBase.

This class is ultimately implemented in terms of the nanokernel tick, and therefore the granularity of the generated events is limited to the period of this timer. This is variant specific, but is usually 1 millisecond.

Note that the CTimer active object uses an RTimer.

Member Function Documentation

After ( TRequestStatus &, TTimeIntervalMicroSeconds32 )

IMPORT_C void	After	(	TRequestStatus &	aStatus,
			TTimeIntervalMicroSeconds32	anInterval
		)

Requests an event after the specified interval.

The counter for this type of request stops during power-down. A 5 second timer will complete late if, for example, the machine is turned off 2 seconds after the request is made.

Parameters
aStatus	On completion, contains the status of the request. This is KErrNone if the timer completed normally at the requested time, otherwise another of the system-wide error codes.
anInterval	The time interval, in microseconds, after which an event is to occur.

Panic Codes
USER	87, if aInterval is negative.
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

AfterTicks ( TRequestStatus &, TInt )

IMPORT_C void	AfterTicks	(	TRequestStatus &	aStatus,
			TInt	aTicks
		)

Requests an event after the specified interval.

The counter for this type of request stops during power-down. A 5 tick timer will complete late if, for example, the machine is turned off 2 ticks after the request is made.

Parameters
aStatus	On completion, contains the status of the request. This is KErrNone if the timer completed normally at the requested time, otherwise another of the system-wide error codes.
aTicks	The time interval, in system ticks, after which an event is to occur.

Panic Codes
USER	87, if aTicks is negative.
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

AgainHighRes ( TRequestStatus &, TTimeIntervalMicroSeconds32 )

IMPORT_C void	AgainHighRes	(	TRequestStatus &	aStatus,
			TTimeIntervalMicroSeconds32	anInterval
		)

Requests an event at a specified time after the last expiry of the this timer object, to a resolution of 1ms. If the last usage of this timer object was not via either this function or RTimer::HighRes(), this call behaves the same as RTimer::HighRes(). The "HighRes timer" counter stops during power-down (the same as "after timer").

Parameters
aStatus	On completion, contains the status of the request. This is KErrNone if the timer completed normally at the requested time, otherwise another of the system-wide error codes. In particular KErrArgument indicates that the requested expiry time has already passed.
anInterval	The time interval, in microseconds, after which an event is to occur, measured from the last expiry time (or intended expiry time in the case where the timer was cancelled) of this timer object. Note that the interval is allowed to be negative. To see why this might be useful consider the following sequence of timer operations: 1. Timer expires at time T 2. AgainHighRes(1000000) - timer is queued for T + 1 sec 3. Cancel() - timer is not queued but last scheduled expiry is still at T + 1 second 4. AgainHighRes(-500000) 5. Timer expires at time T + 0.5 second

Parameters

aStatus

On completion, contains the status of the request. This is KErrNone if the timer completed normally at the requested time, otherwise another of the system-wide error codes. In particular KErrArgument indicates that the requested expiry time has already passed.

anInterval

The time interval, in microseconds, after which an event is to occur, measured from the last expiry time (or intended expiry time in the case where the timer was cancelled) of this timer object. Note that the interval is allowed to be negative. To see why this might be useful consider the following sequence of timer operations: 1. Timer expires at time T 2. AgainHighRes(1000000) - timer is queued for T + 1 sec 3. Cancel() - timer is not queued but last scheduled expiry is still at T + 1 second 4. AgainHighRes(-500000) 5. Timer expires at time T + 0.5 second

Panic Codes
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

At ( TRequestStatus &, const TTime & )

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

Requests an event at a given system time (in the current time zone).

If the machine is off at that time, it is automatically turned on.

Parameters
aStatus	On completion, contains the status of the request: KErrNone, the timer completed normally at the requested time; KErrCancel, the timer was cancelled; KErrAbort, the timer was aborted because the system time changed; KErrUnderflow, the requested completion time is in the past; KErrOverFlow, the requested completion time is too far in the future;
aTime	The time at which the timer will expire.

Panic Codes
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

AtUTC ( TRequestStatus &, const TTime & )

IMPORT_C void	AtUTC	(	TRequestStatus &	aStatus,
			const TTime &	aUTCTime
		)

Requests an event at a given UTC time.

If the machine is off at that time, it is automatically turned on.

Parameters
aStatus	On completion, contains the status of the request: KErrNone, the timer completed normally at the requested time; KErrCancel, the timer was cancelled; KErrAbort, the timer was aborted because the system time changed; KErrUnderflow, the requested completion time is in the past; KErrOverFlow, the requested completion time is too far in the future;

Panic Codes
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

Cancel ( )

IMPORT_C void

Cancel

(

)

Cancels any outstanding request for a timer event.

Any outstanding timer event completes with KErrCancel.

CreateLocal ( )

IMPORT_C TInt

CreateLocal

(

)

Creates a thread-relative timer.

Return Value: KErrNone if successful, otherwise another of the system-wide error codes.

HighRes ( TRequestStatus &, TTimeIntervalMicroSeconds32 )

IMPORT_C void	HighRes	(	TRequestStatus &	aStatus,
			TTimeIntervalMicroSeconds32	anInterval
		)

Requests an event after the specified interval to a resolution of 1ms. The "HighRes timer" counter stops during power-down (the same as "after timer").

Parameters
aStatus	On completion, contains the status of the request. This is KErrNone if the timer completed normally at the requested time, otherwise another of the system-wide error codes.
anInterval	The time interval, in microseconds, after which an event is to occur.

Panic Codes
USER	87, if aInterval is negative.
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

Inactivity ( TRequestStatus &, TTimeIntervalSeconds )

IMPORT_C void	Inactivity	(	TRequestStatus &	aStatus,
			TTimeIntervalSeconds	aSeconds
		)

Requests an event to be triggered when aSeconds is exactly, (ie not greater or less than), the time elapsed (to the nearest second) since the last user activity. If the event trigger time has been "missed", instead of triggering late, the timer waits for the next user activity, to try and satisfy the condition.

That is to say, if there was user activity within the last aSeconds, the event will be triggered after aSeconds of continuous inactivity following that activity. Otherwise, if there has been no such activity within this time, an event is triggered after aSeconds of continuous inactivity following the next user activity in the future.

It follows from this, that you can request an event directly after the next user activity by supplying a time interval of zero.

Parameters
aStatus	On completion, contains the status of the request: KErrNone, the timer completed normally; KErrCancel, the timer was cancelled; KErrArgument, if aSeconds is less then zero; KErrOverflow, if aSecond reaches its limit (which is platform specific but greater then one and a half day).
aSeconds	The time interval in seconds.

Panic Codes
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.

Lock ( TRequestStatus &, TTimerLockSpec )

IMPORT_C void	Lock	(	TRequestStatus &	aStatus,
			TTimerLockSpec	aLock
		)

Requests an event on a specified second fraction.

Parameters
aStatus	On completion, contains the status of the request: KErrGeneral, the first time this is called; KErrNone, the timer completed normally at the requested time; KErrCancel, the timer was cancelled; KErrAbort, the timer was aborted because the system time changed; KErrUnderflow, the requested completion time is in the past; KErrOverFlow, the requested completion time is too far in the future.
aLock	The fraction of a second at which the timer completes.

Panic Codes
KERN-EXEC	15, if this function is called while a request for a timer event is still outstanding.