Notification Request Tutorial

This tutorial describes how to receive notification of the events with the telephony API for applications.

CTelephony can notify the client applications about the status changes to the events like:

to detect inbound calls
to detect the phone charger connection
battery charge information

The client applications can get the notification of the events that contain a notification event, an information class and a cancellation code. For example, the Voice Line Status event describes that the client applications can receive the notification when it changes. The event description contains:

Item	Description
CTelephony::EVoiceLineStatusChange	notification event
CTelephony::TCallStatus	information class
CTelephony::EVoiceLineStatusChangeCancel	cancellation code

create an instance of CTelephony

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

create an instance of the class, passing it the pointer to CTelephony

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

call the object's RequestNotification method to start the request. This calls CTelephony::NotifyChange()
```
exampleObject->RequestNotification();
```
pass 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 The new status will have been written into the TCallStatus object that was given to NotifyChange()
you can see all the notification events in CTelephony::TNotificationEvent. This also shows which information class is associated with each event
you can cancel a request for notification any time before the operation finished. Do this by passing CTelephony::CancelAsync() the cancellation code
Note: You should not request notification before the previous notification request is either completed or cancelled. The notification request is started after the active object is created, so there could not be a request. If you are <bold>not</bold> sure that previous requests for that object have completed, call theCActive::Cancel method before issuing a new request:
```
exampleObject->Cancel();exampleObject->RequestNotification();
```
This will cancel any previous requests.

Voice line status example

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 asynchronous 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 );
    }

Receive notification of other events

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--- );
    }
```

Parent topic: Telephony API for Applications