CUserActivityManager Class Reference

class CUserActivityManager : public CTimer

The CUserActivityManager API allows clients to easily monitor for user inactivity and activity. It is a key part in implementing functionality such as power management and screen savers.

Clients construct the object using NewL() and call Start() to register callbacks to begin [in]activity monitoring. Monitoring continues until the object is destroyed. Clients can call SetInactivityTimeout() to adjust the inactivity interval once started.

Callbacks supplied by clients should:
  • complete quickly with minimal blocking.

  • never call CUserActivityManager APIs as reentrancy is not supported.

  • never leave otherwise it can lead to panics.

This API uses "CUserActivityManager" category panics for its error strategy as it has few error return code paths. Specific panics raised by APIs through improper use can be seen in the API documentation. KErrGeneral is raised when the internal state is irrecoverable.

CTimer TCallback

Inherits from

Constructor & Destructor Documentation

CUserActivityManager(TInt)

CUserActivityManager ( TInt aPriority ) [private]

Default constructor.

Parameters

TInt aPriority Priority for the CTimer.

~CUserActivityManager()

IMPORT_C ~CUserActivityManager ( )

Destructor.

Member Functions Documentation

MonitorInactivity()

void MonitorInactivity ( ) [private]

This method attempts to enter inactivity monitoring mode. For this to occur the current ellapsed inactivity must be less than the iInterval otherwise it will invoke the inactivity callback and enter activity monitoring mode.

CTimer::Inactivity() RTimer::Inactivity()

NewL(TInt)

IMPORT_C CUserActivityManager * NewL ( TInt aPriority ) [static]

Factory function used to allocate and construct a new CUserActivityManager object.

leave
KErrNoMemory When memory allocations fail
leave
... Any other one of the other system wide error codes

Parameters

TInt aPriority Priority for the CTimer active object.

RunL()

void RunL ( ) [private, virtual]

This is called from CActiveScheduler when the timer registered using the CTimer::Inactivity() call expires. This could indicate user inactivity or activity, iStatus is checked to determine which condition has been detected by CTimer .

If the manager is in inactivity monitoring mode the iInactiveCallback will be invoked and the manager will switch to monitoring for activity. If the manager is in activity monitoring mode the iActiveCallback will be invoked and the manager will attempt to switch to monitoring for inactivity. This attempt may fail and it will remain in activity monitoring mode if an iInterval amount of inactivity has passed since RunL() was invoked.

When CActive::iStatus indicates and error a panic is raised in debug builds. In release builds it returns to the active scheduler to handle.

CUserActivityManager::MonitorInactivity() CTimer::Inactivity() RTimer::Inactivity()

SetInactivityTimeout(TTimeIntervalSeconds)

IMPORT_C void SetInactivityTimeout ( TTimeIntervalSeconds aInterval )

Re-starts activity monitoring with a new inactivity interval. See Start() for behavioural description.

Requires Start() to have been called previously otherwise the method will panic in debug builds if Start() has not be called before hand to set up at least one callback. This prevents wasting CPU cycles/power on monitoring when no action will take place.

CUserActivityManager::Start()
panic
"CUserActivityManager" KErrNotSupported Raised when aInterval is not positive in debug builds
panic
"CUserActivityManager" KErrNotReady Raised when Start() has not yet been called in debug builds.

Parameters

TTimeIntervalSeconds aInterval New inactivity interval in seconds.

Start(TTimeIntervalSeconds, TCallBack, TCallBack)

IMPORT_C void Start ( TTimeIntervalSeconds aInterval,
TCallBack aInactiveCallback,
TCallBack aActiveCallback
)

Starts the user activity monitoring using the callbacks supplied with the specify inactivity interval in seconds. If aInterval is not positive then in release builds it assumes an interval of 1 second but in debug builds it will panic. The function pointers in the callback arguments may be NULL if the client is not interested in one or other events.

When called following construction or while inactivity is being monitored the manager will enter/stay in inactivity monitoring mode when aInterval is larger than the current elapsed inactivity time at the time of the call and aInactiveCallback will be called first. Otherwise it will invoke aInactiveCallback immediately and enter activity monitoring mode and aActiveCallback will be called next.

When called while user activity is being monitored the manager will stay in activity monitoring mode and aActiveCallback will be called first.

panic
"CUserActivityManager" KErrNotSupported raised when when aInterval is not positive in DEBUG builds
CTimer::Inactivity() RTimer::Inactivity()

Parameters

TTimeIntervalSeconds aInterval Inactivity interval in seconds.
TCallBack aInactiveCallback This callback is used when there has not been user activity for aInterval seconds.
TCallBack aActiveCallback This callback is used when user activity is detected after an inactivity period longer or equal to aInterval seconds.

Member Enumerations Documentation

Enum TState

Enumerators

EStUndefined = 0
EStNotActive
EStMonForInactivity
EStMonForActivity

Member Data Documentation

TCallBack iActiveCallback

TCallBack iActiveCallback [private]

Callback to be used in case of user activity after inactivity period

TCallBack iInactiveCallback

TCallBack iInactiveCallback [private]

Callback to be used in case that user inactivity is detected

TTimeIntervalSeconds iInterval

TTimeIntervalSeconds iInterval [private]

Inactivity interval

TState iState

TState iState [private]

State of object, what form of monitoring is active.