How to request notification when information changes

CTelephony can notify you when certain information in the phone changes. Typical uses are to detect incoming calls, to detect when the phone charger is unplugged or when the battery is about to run out. There are examples of these below.

Find out about the phone lists many items of information. Each item's description will tell you whether CTelephony can notify you when it changes. If so, the description will specify a notification event, an information class and a cancellation code:

For example, the description of the Voice Line Status says that you can receive notification when it changes. This status indicates whether the line is being used to make a call, whether the line is ringing and and could be answered, whether there is a call on hold etc. The description says to use CTelephony::EVoiceLineStatusChange notification event, the CTelephony::TCallStatus information class and the CTelephony::EVoiceLineStatusChangeCancel cancellation code

You can see all the notification events in CTelephony::TNotificationEvent. This also shows which information class is associated with each event.

Request notification with CTelephony::NotifyChange(), passing it the notification event and an empty instance of the information class. This method starts an asynchronous operation that completes when the requested notification event occurs.

For instance, the EVoiceLineStatusChange event occurs when the voice line status changes. At this point, the asynchronous operation completes, giving your code the oppurtunity to respond to the event. The new status will have been written into the TCallStatus object that was given to NotifyChange(), allowing your code the see the new signal stength. Rememember that the TCallStatus does not contain valid information until this point.

You can cancel a request for notificaton any time before the operation finished. Do this by passing CTelephony::CancelAsync() the cancellation code.

Here is an active object that detects a change in voice line status. It doesn't do much when the voice line status changes; it simply stores the new status values and then starts the next asynchonous operation.

This is a basic Active Object. You will need to know about active objects in order to use CTelephony's notification abilities.

   /*

   Example CTelephony Notification
   -------------------------------

   This class uses the CTelephony API to get notification when a
   phone's voice line status changes.

   This class is an active object.  You will need to have knowledge of
   active objects in order to understand this class.  All active
   object are derived from CActive.

   This program can be easily modified to get notification when other
   events occur.

   See CTelephony::TNotificationEvent for a list of
   events.

   */

   #include <e32base.h>
   #include <Etel3rdParty.h>

class CNotifyExample : public CActive
    {

public:
    // Constructor/Destructor
    CNotifyExample( CTelephony* aTelephony );

    // Request voice line status change notification
    void RequestNotification();

private:
    /*
       These are the pure virtual methods from CActive that
       MUST be implemented by all active objects
      */
    void RunL();
    void DoCancel();

private:

    /*
       A reference to a CTelephony, obtained with CTelephony::NewL()
       or NewLC()
       */
    CTelephony* iTelephony;

    /*
       When the voice line status changes (and hence the asynchronous
       operation completes) the new voice line status is written into
       iLineStatus. Until this point, iLineStatus is not valid.

       If you change this class to get notification of other events,
       then change this class. CTelephony::TNotificationEvent lists
       the classes associated with each event.
       */
    CTelephony::TCallStatusV1 iLineStatus;
    CTelephony::TCallStatusV1Pckg iLineStatusPckg;
    };

/*
   Default constructor.  Pass it a reference to a CTelephony, created
   with CTelephony::NewL() or NewLC()
   */
CNotifyExample::CNotifyExample( CTelephony* aTelephony )
    : CActive( EPriorityStandard ),
      iTelephony( aTelephony ),
      iLineStatusPckg( iLineStatus )
    {
        //default constructor
        iLineStatus.iStatus = CTelephony::EStatusUnknown;
    }

/*
   This method requests notification by calling
   CTelephony::NotifyChange() to initialise an asynchronous operation.
   Then it immediately calls CActive::SetActive to start the
   operation.  The operation completes when the notification event
   occurs.

   In this case, we tell CTelephony to wait for the
   CTelephony::EVoiceLineStatusChange notification event, hence the
   event occurs when the voice line status changes.

   For other events, change the notification event in the call to
   CTelephony::NotifyChange().  The CTelephony::TNotificationEvent
   description  all the notification events.
   It also list the information class to
   pass to CTelephony::NotifyChange().  The TCallStatus
   class is associated with CTelephony::EVoiceLineStatusChange.
   */
void CNotifyExample::RequestNotification()
    {

    /*
       Panic if this object is already performing an asynchronous
       operation
       */
    _LIT( KNotifyExamplePanic, "CNotifyExample" );
    __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 ));

    iTelephony->NotifyChange( iStatus,
                              CTelephony::EVoiceLineStatusChange,
                              iLineStatusPckg );
    SetActive();
    }

/*
   The active object's RunL method is called when the asynchronous
   event completes.  In this case, RunL is called when the voice line
   status changes.  When this occurs, the new voice line status is
   written to the iLineStatus.  iLineStatus was passed to
   CTelephony::NotifyChange() when the asynchronous operation was
   started.

   This is where you put your code to respond to your chosen
   notification event.

   In all active objects, iStatus indicates whether the asynchronous
   operation succeeded, failed, or is still in progress.  KErrNone
   indicates success, and hence the value in iStatus is valid.
   */
void CNotifyExample::RunL()
    {
    if( iStatus==KErrNone )
       {
       /*
          Insert code to respond to the change of voice line status
          here.  A typical use to answer a call if the voice line
          status is 'ringing' (EStatusRinging)

          Remember that you must implement a RunError() method if
          your code in RunL can leave.
          */
       if( iLineStatus.iStatus == CTelephony::EStatusRinging )
            ;  // Answer call by calling 'AnswerIncomingCall()'

       /* Request the next notification */
       iTelephony->NotifyChange( iStatus,
                              CTelephony::ESignalStrengthChange,
                              iLineStatusPckg );
       SetActive();
       }
    }

/*
   Like all active objects, you must supply a DoCancel() method to
   cancel the asynchronous operation.  This must cancel a CTelephony
   notification operation with CTelephony::CancelAsync.  Give the method
   the appropriate 'cancellation event' from those in 'TCancellationRequest'

   In this case, we are cancelling the "voice line status Change" event,
   and so we need to supply the EVoiceLineStatusChange cancellation code.
   If you change this class to respond to a different notification
   event, remember to change the call to CTelephony::CancelAsync.
   */
void CNotifyExample::DoCancel()
    {
    iTelephony->CancelAsync( CTelephony::EVoiceLineStatusChangeCancel );
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

You use the class as follows:

1. Create an instance of CTelephony:

   CTelephony* telephonyApi = CTelephony::NewL();
   CleanupStack::PushL( telephonyApi );

2. Create an instance of the class, passing it the pointer to CTelephony:

   CNotifyExample *exampleObject = new CNotifyExample( telephonyApi );
   CleanupStack::PushL( exampleObject );

3. Call the object's RequestNotification method to start the request. This calls CTelephony::NotifyChange():

   exampleObject->RequestNotification();

Not that you should never request notification before the previous notification request was either completed or cancelled. In the situation above, the notification request was started just after the active object was created, so there could not be a request already in progress. If you are not sure that previous requests for that object have completed, then call the object's GOT TO HERE. CActive::Cancel method before issuing the new request:

exampleObject->Cancel();
exampleObject->RequestNotification();

This will cancel any previous requests. CNotifyExample::DoCancel will be called as part of the cancelling process.

The previous examples detect changes in voice line status. You can adapt this example for other events as follows:

• In the RequestNotification() method, pass CTelephony::NotifyChange() the notification event you want to detect, listed in CTelephony::TNotificationEvent. Each event has an information class associated with it, which stores the new information after it has changed. Pass NotifyChange() an instance of the information class, too:

  CNotifyExample::RequestNotification()
      {
      _LIT( KNotifyExamplePanic, "CNotifyExample" );
      __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 ));
          
      iTelephony->NotifyChange( iStatus, 
                                ---Insert notification event---
                                ---Insert packaged information class instance--- );
      SetActive();
      }

  You will need to declare the information class instance in the CNotifyExample's declaration.

• Change the code in CNotifyExample::RunL that handles the event.

• Change the DoCancel method to cancel the correct event. Insert the correct cancellation code from those in CTelephony::TCancellationRequest:

  CNotifyExample::DoCancel()
      {
      iTelephony->CancelAsync(---Insert cancellation code--- );
      }