How to use a change notifier

To use a change notifier, a thread:

• constructs an RChangeNotifier handle and then calls its Create() member function to create the associated Kernel side object. The RChangeNotifier handle is thread-relative which means that the handle is closed if the thread dies.

• issues a request to be notified when the next change occurs, passing a TRequestStatus object. This is a call to the Logon() function.

When a change occurs, the change information is made available to the thread through the TRequestStatus object and the thread's request semaphore is signalled to indicate that the request is complete.

The following code fragments demonstrates this:

{
...
RChangeNotifier the_notifier;
TRequestStatus  the_status;
...
the_notifier.Create();
the_notifier.Logon(the_status);
User::WaitForRequest(the_status);
...
...// prepare for a long wait
...
TInt changes = the_status.Int();
if (changes & EChangesSystemTime)
    {
    // handle a change to system time
    }
if (changes & EChanges EChangesLocale)
    {
    // handle a change to locale
    }
...
the_notifier.Close();
...
}

In practical code, an RChangeNotifier would be part of an active object.

The RChangeNotifier handle also offers the LogonCancel() function. Calling this function, causes the thread's request semaphore to be signalled and any wait to complete. The TRequestStatus is set to KErrCancel.

The above technique for checking changes is used because, at the completion of a notification request, any, or all, changes may be reported. Code should make no assumptions about the other bits in the returned value. In other words, code should be prepared for a notification request to complete without an 'interesting' change.

Users should also note that the first notification request after creation of an RChangeNotifier, completes immediately; the changes reported are all those defined by the TChanges enum.

Also note that after a notification request completes, other changes may occur before the user of the RChangeNotifier can issue the next notification request. If this occurs, any change events are collected by the change notifier; they are not lost; in this situation, the next notification request completes immediately.