Environment changes

The Environment Change Notifier informs an application about changes in the system environment. The class that implements the API is CEnvironmentChangeNotifier, which is an active object. The following changes are notified:

  • Change of system locale

  • System time passes midnight

  • System time changes

  • Death of any thread

  • Status of the power supply changes

To receive environment change events, a TCallBack object must be created. The constructor of the callback object takes two parameters: The first is the pointer to the function to be called when an event occurs and the second is a pointer to the object that implements the function.

TCallBack( TInt ( *aFunction )( TAny* aPtr ) )

The CEnvironmentChangeNotifier object takes two parameters. The first one is a priority of the active object and the second one is a reference to the callback object.

static CEnvironmentChangeNotifier* NewL(TInt aPriority, const TCallBack& aCallBack)

The Start() function is called in order to start observation.

void Start()

When an environment change event occurs, the function whose pointer was given to the callback object is called. Details about an event that occurred can be queried using the Change() function.

TInt Change() const

The function returns a bit pattern, where each bit value corresponds to one of the enumerations defined in TChanges (e32const.h).

enum TChanges
    EChangesLocale = 0x01,
    EChangesMidnightCrossover = 0x02,
    EChangesThreadDeath = 0x04,
    EChangesPowerStatus = 0x08,
    EChangesSystemTime = 0x10,
    EChangesFreeMemory = 0x20,
    EChangesOutOfMemory = 0x40,

Code example:

void CExampleEnvChangeNotifier::ConstructL()
    iCallBack = new( ELeave )TCallBack( CallBackFunction, this );
    iChangeNotifier =
    CEnvironmentChangeNotifier::NewL( 0, *iCallBack );
    delete iChangeNotifier;
    delete iCallBack;
TInt CExampleEnvChangeNotifier::CallBackFunction( TAny* aFunction )
    return( (CEventsEnvChangeNotifier* )aFunction )->ChangeL();
TInt CExampleEnvChangeNotifier::ChangeL()
    TInt change = iChangeNotifier->Change();
    if( change & EChangesLocale )
        // Locale change, do something
    if( change & EChangesMidnightCrossover )
        // Midnight crossover, do something
    if( change & EChangesThreadDeath )
        // Thread death, do something
    if( change & EChangesPowerStatus )
        // Power status change, do something
    if(change & EChangesSystemTime )
        // System status change, do something
    return 1;