Class RTimer

class RTimer : public RHandleBase;

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.

Derivation

• RHandleBase - A handle to an object
• RTimer - Asynchronous timer services

Members

Defined in RTimer:
After(), AfterTicks(), At(), AtUTC(), Cancel(), CreateLocal(), HighRes(), Inactivity(), Lock()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), Open(), SetHandle(), SetHandleNC(), SetReturnedHandle(), iHandle

IMPORT_C TInt CreateLocal();

Description

Creates a thread-relative timer.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

IMPORT_C void Cancel();

Description

Cancels any outstanding request for a timer event.

Any outstanding timer event completes with KErrCancel.

IMPORT_C void After(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 anInterval);

Description

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

TRequestStatus &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. TTimeIntervalMicroSeconds32 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.

IMPORT_C void AfterTicks(TRequestStatus &aStatus, TInt aTicks);

Description

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

TRequestStatus &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. TInt 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.

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

Description

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

TRequestStatus &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; const TTime &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.

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

Description

Requests an event at a given UTC time.

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

Parameters

TRequestStatus &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; const TTime &aUTCTime

Panic codes

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

IMPORT_C void Lock(TRequestStatus &aStatus, TTimerLockSpec aLock);

Description

Requests an event on a specified second fraction.

Parameters

TRequestStatus &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. TTimerLockSpec 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.

IMPORT_C void Inactivity(TRequestStatus &aStatus, TTimeIntervalSeconds aSeconds);

Description

Requests an event if the specified time interval elapses without user actvity.

If there has already been a period of user inactivity greater than the specified interval, then the timer is set after the next user activity.

Parameters

TRequestStatus &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). TTimeIntervalSeconds aSeconds The time interval.

Panic codes

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

IMPORT_C void HighRes(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 anInterval);

Description

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

TRequestStatus &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. TTimeIntervalMicroSeconds32 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.