Class CTimer

CTimer

Support

Supported from 5.0

Description

Base class for a timer active object.

This is an active object that uses the asynchronous services provided by RTimer, to generate events. These events occur either at a specific time specified as a TSystemTime, or after an interval specified in twelfths of a second.

The RunL() virtual member function is called by the active scheduler after this event occurs.

To write a class derived from CTimer, first define and implement a constructor through which the priority of the CTimer active object can be specified. Then define and implement a suitable RunL() function to handle the completion of a timer request. This function is not defined by CTimer itself and must, therefore, be provided by the derived class.

Note that the CPeriodic and CHeartbeat classes are derived from CTimer, and answer most timing needs.

Derivation

CActive The core class of the active object abstraction CBase Base class for all classes to be instantiated on the heap CTimer Base class for a timer active object

Defined in CTimer:
After(), At(), CTimer(), ConstructL(), Inactivity(), Lock(), ~CTimer()

Inherited from CActive:
Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
operator new()

See also:

• CHeartbeat

protected: CTimer(TInt aPriority);

Description

Protected constructor with priority. Use this constructor to set the priority of the active object.

Classes derived from CTimer must define and provide a constructor through which the priority of the active object can be passed. Such a constructor can call CTimer's constructor in its constructor initialisation list.

Parameters

TInt aPriority The priority of the timer.

protected: void ConstructL();

Description

Constructs a new asynchronous timer. The function must be called before any timer requests (i.e. calls to RTimer::After() or RTimer::At()) can be made.

Since it is protected, it cannot be called directly by clients of CTimer derived classes. Typically, a derived class makes a base call to this function in the second phase of two-phase construction; i.e. the derived class defines and implements its own ConstructL() function within which it makes a base call to CTimer::ConstructL().

~CTimer();

Description

Frees resources prior to destruction. Specifically, it cancels any outstanding request and closes the RTimer handle.

void After(TTimeIntervalMicroSeconds32 anInterval);

Description

Requests an event after an interval.

The "after timer" completes after the specified number of microseconds. The "after timer" counter stops during power-down. Therefore, a 5-second timer will complete late if the machine is turned off 2 seconds after the request is made.

Notes:

• The CTimer’s RunL() function will be run as soon as possible after the specified interval.

• The RunL() may be delayed because the RunL() of another active object, with the deepest nesting-level active scheduler on the same thread, is running when the event occurs: this cannot be avoided, but can be minimised by making all RunL()s of short duration.

• The RunL() may be delayed because other, higher-priority, active objects are scheduled instead. This can be avoided by making CTimers very high-priority.

Parameters

TTimeIntervalMicroSeconds32 anInterval Interval after which event is to occur, in microseconds. If this value is negative, the underlying RTimer raises a USER 87 panic.

void At(const TTime& aTime);

Description

Requests an event at a given system time.

The "at timer" completes at the specified time — if the machine is in a turned off state at that time, the machine will be turned on again.

Notes:

• The CTimer’s RunL() function will be run as soon as possible after the specified system time.

• The RunL() may be delayed because the RunL() of another active object, with the deepest nesting-level active scheduler on the same thread, is running when the event occurs: this cannot be avoided, but can be minimised by making all RunL()s of short duration.

• The RunL() may be delayed because other, higher-priority, active objects are scheduled instead. This can be avoided by making CTimers very high-priority.

Parameters

const TTime& aTime The time at which the event is to occur.

void Lock(TTimerLockSpec aLock);

Description

Requests an event on a specified second fraction.

Note:

• The RunL() function is run exactly on the specified second fraction.

Parameters

TTimerLockSpec aLock The fraction of a second at which the timer completes.

void Inactivity(TTimeIntervalSeconds aSeconds);

Support

Supported from 6.0

Description

Requests an event if no activity occurs within the specified interval.

Parameters

TTimeIntervalSeconds aSeconds The time interval.